> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/start-here/programmatic-onboarding.md).

# Programmatic onboarding

Use this path when an **agent**, **CI job**, or **integration** should set up The Grid over HTTP, without copying secrets from the dashboard.

For 99% of programmatic onboarding the flow is three steps: log in with OAuth, create a consumption API key, make your first inference request. Trading setup is optional and covered at the end.

## Prerequisites

* A Grid account at [app.thegrid.ai](https://app.thegrid.ai)
* An OAuth `client_id` (see below)
* A browser or human step to approve the device login once per grant

### Picking a client\_id

Device flow requests identify your integration with a `client_id` for a registered OAuth application:

* **CLI and personal agent flows:** use the public client `grid-cli-public`. It is the application behind the Grid CLI and works for device login today.
* **Server-side products and integrations:** register a dedicated OAuth application so grants show your product's name. Contact <support@thegrid.ai> to register one; self-serve app registration is not available yet.

Check which scopes a client may request before you start:

```bash
curl -sS "https://platform.api.thegrid.ai/v1/oauth/scopes?client_id=grid-cli-public"
```

## Production URLs

| Surface                                                                     | Base URL                             |
| --------------------------------------------------------------------------- | ------------------------------------ |
| [Consumption API](/docs/api-reference/consumption-api.md) (inference)       | `https://api.thegrid.ai/v1`          |
| [Platform API](/docs/api-reference/platform-api.md) (OAuth, keys, settings) | `https://platform.api.thegrid.ai/v1` |
| [Trading API](/docs/api-reference/trading-api.md) (markets, orders)         | `https://trading.api.thegrid.ai/v1`  |

Anthropic Messages format: `https://messages-beta.api.thegrid.ai/v1` (same consumption key, `x-api-key` header).

## Step 1: Log in with the OAuth device flow

Request a device code ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)):

```bash
curl -sS -X POST "https://platform.api.thegrid.ai/v1/oauth/device/code" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "grid-cli-public",
    "scope": "account:read keys:manage"
  }'
```

The response includes `user_code`, `verification_uri` (typically `https://app.thegrid.ai/activate`), `device_code`, `expires_in`, and `interval` (seconds between polls).

Open `verification_uri`, sign in, and approve the requested scopes.

Poll for tokens until you receive `access_token` or an error other than `authorization_pending`:

```bash
curl -sS -X POST "https://platform.api.thegrid.ai/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "client_id": "grid-cli-public",
    "device_code": "DEVICE_CODE_FROM_STEP_1"
  }'
```

Save `access_token` (`grid_at_*`) and `refresh_token` (`grid_rt_*`). Access tokens expire in about one hour; refresh with the same token endpoint and `grant_type=refresh_token`.

## Step 2: Create a consumption API key

Requires `keys:manage` on the access token.

```bash
export ACCESS_TOKEN="grid_at_…"

curl -sS -X POST "https://platform.api.thegrid.ai/v1/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_key": {"name": "my-agent"}}'
```

The response `data.key` is the consumption secret. Store it immediately. List and show endpoints return `key: null` afterward.

## Step 3: Make your first inference request

```bash
export CONSUMPTION_KEY="…"   # from data.key

curl -sS -L "https://api.thegrid.ai/v1/chat/completions" \
  -H "Authorization: Bearer $CONSUMPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-prime", "messages": [{"role": "user", "content": "Hello"}]}'
```

Use `-L` with curl so the Consumption API `307` redirect is followed. See [Request routing and redirects](/docs/api-reference/request-routing-and-redirects.md).

That's it. Point your OpenAI-compatible client at `https://api.thegrid.ai/v1` with the consumption key and you are onboarded. See [General Agent Skill](/docs/integrations-and-best-practices/integrations/general-agent-skill.md) for client setup and 402 handling, and the guides under [Integrations](/docs/integrations-and-best-practices/integrations.md) for specific frameworks.

## Optional: trading setup

Skip this section unless you want to read balances, list trades, or place orders yourself instead of letting [Auto Mode](/docs/start-here/auto-mode-vs-advanced-mode.md) buy on your behalf. You will need the `account:write` and `trade:*` scopes in Step 1 in addition to the ones above.

### Register a trading signing key

Generate an Ed25519 keypair locally (see [Authentication](/docs/api-reference/authentication.md#trading-keys)), then register the public key:

```bash
curl -sS -X POST "https://platform.api.thegrid.ai/v1/signing-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signing_key": {
      "label": "my-bot",
      "public_key": "BASE64_RAW_32_BYTE_PUBLIC_KEY"
    }
  }'
```

Use the returned `fingerprint` as `x-thegrid-fingerprint` when signing Trading API requests. The private key never leaves your machine.

### Enable trading on the account

Trading requires [Advanced Mode](/docs/start-here/auto-mode-vs-advanced-mode.md). Switch with `account:write`:

```bash
curl -sS -X POST "https://platform.api.thegrid.ai/v1/self/system-settings/account-mode" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "advanced"}'
```

Note that some account settings are read-only results of the account mode. The settings `GET` lists them in `mode_managed_fields`; writes that diverge from what the mode dictates return `403`. Details and all settings endpoints: [Platform API reference](/docs/api-reference/platform-api.md#account-settings).

### Start trading

From here the [Trading API](/docs/api-reference/trading-api.md) covers markets, balances, order placement, and transfers, authenticated with your signing key.

## Where next

* [Consumption API](/docs/api-reference/consumption-api.md): inference endpoints and request shapes
* [Platform API](/docs/api-reference/platform-api.md): full OAuth, key, and settings reference
* [Authentication](/docs/api-reference/authentication.md): credential types and the signing scheme
* [Quickstart](/docs/start-here/quickstart.md): first inference call with a dashboard-created key
* [Auto Mode and Advanced Mode](/docs/start-here/auto-mode-vs-advanced-mode.md): what the account modes mean


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/start-here/programmatic-onboarding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.