Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt

Use this file to discover all available pages before exploring further.

For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending .md to its URL or sending Accept: text/markdown.
The Account API lets your application call Parallel programmatically on behalf of a user without prompting them to paste an API key. Authentication uses the OAuth 2.0 Device Authorization Grant (RFC 8628), which is designed for clients without a browser or with limited input — CLIs, IDE plugins, IoT devices, and similar. The flow produces an access token that you pass as a Bearer token on every Account API request. See the full endpoint reference in the Account API tab in the navigation.
The Parallel CLI handles the entire device-OAuth flow for you — register, device code, polling, refresh, and revoke — and exposes every Account API endpoint as a regular CLI command. If you don’t need to embed the flow in your own application, the CLI is the fastest way to use the Account API. The rest of this page describes what the CLI does under the hood, for clients that need to implement it themselves.

​
Base URL

All endpoints below are rooted at: 
https://platform.parallel.ai

​
Overview

The full lifecycle is:
  1. Register your client once, to obtain a client_id.
  2. Request a device code to start an authorization session.
  3. Prompt the user to verify in their browser using the verification URL and user code returned in step 2.
  4. Poll the token endpoint until the user approves and you receive an access_token and refresh_token.
  5. Call the Account API with Authorization: Bearer <access_token>.
  6. Refresh the access token when it expires, or revoke the refresh token when the user signs out.
The access_token returned by step 4 is what authorizes Account API calls. Without a valid bearer token, requests to the Account API will be rejected.

​
1. Register your client

Register your application once to receive a client_id. Send a description of your client and the platform it runs on: 
POST https://platform.parallel.ai/getServiceKeys/register
Content-Type: application/json
Accept: application/json

{
  "client_name": "your-app-name",
  "platform": {
    "machine": "arm64",
    "os_name": "posix",
    "processor": "arm",
    "release": "24.6.0",
    "system": "Darwin",
    "version": "Darwin Kernel Version 24.6.0"
  }
}
The response contains a client_id you reuse for all subsequent device-code requests from the same installation.

​
2. Request a device code

Start an authorization session by requesting a device code. The body is application/x-www-form-urlencoded: 
POST https://platform.parallel.ai/getServiceKeys/device/code
Content-Type: application/x-www-form-urlencoded
Accept: application/json

client_id={clientId}&scope={scope}
The response includes:
  • device_code — opaque code your client uses when polling the token endpoint.
  • user_code — short code the user types in the browser.
  • verification_uri (and typically verification_uri_complete) — the URL to send the user to.
  • expires_in — lifetime of the device code, in seconds.
  • interval — minimum number of seconds to wait between polls.
Display the user_code and verification_uri to the user, or open verification_uri_complete in their browser directly.

​
3. Poll for the access token

While the user completes verification in the browser, poll the token endpoint at the interval the server specified: 
POST https://platform.parallel.ai/getServiceKeys/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id={clientId}&device_code={deviceCode}
Polling returns one of:
  • authorization_pending — user has not yet approved. Wait interval seconds and try again.
  • slow_down — you are polling too fast. Increase your interval.
  • access_denied — the user rejected the request. Stop polling.
  • expired_token — the device code expired. Restart from step 2.
  • Success — a JSON body containing access_token, refresh_token, token_type (Bearer), and expires_in.
Once you have the access_token, you can call the Account API.

​
4. Call the Account API

Every Account API request must include an Authorization header with the access token from step 3: 
GET https://api.parallel.ai/account/service/...
Authorization: Bearer {accessToken}
Accept: application/json
Requests without a valid bearer token are rejected. The endpoint catalogue is documented in the Account API tab in the navigation.

​
5. Refresh the access token

Access tokens are short-lived. When one expires, exchange your refresh token for a new pair without prompting the user again: 
POST https://platform.parallel.ai/getServiceKeys/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=refresh_token&refresh_token={refreshToken}
The response contains a new access_token and (typically) a new refresh_token. Persist both and use the new pair going forward.

​
6. Revoke a refresh token

When the user signs out, or when you want to invalidate a session, revoke the refresh token: 
POST https://platform.parallel.ai/getServiceKeys/token/revoke
Content-Type: application/x-www-form-urlencoded
Accept: application/json

refresh_token={refreshToken}
After revocation, the refresh token can no longer be used to obtain new access tokens. Existing access tokens remain valid until they expire on their own.

​
End-to-end example

# 1. Register (once per installation)
curl -X POST https://platform.parallel.ai/getServiceKeys/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "my-app",
    "platform": {
      "machine": "arm64",
      "os_name": "posix",
      "processor": "arm",
      "release": "24.6.0",
      "system": "Darwin",
      "version": "Darwin Kernel Version 24.6.0"
    }
  }'

# 2. Request a device code
curl -X POST https://platform.parallel.ai/getServiceKeys/device/code \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID&scope=$SCOPE"

# 3. Poll for the token (after user approves in browser)
curl -X POST https://platform.parallel.ai/getServiceKeys/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=$CLIENT_ID&device_code=$DEVICE_CODE"

# 4. Call the Account API with the bearer token
curl https://api.parallel.ai/account/service/<endpoint> \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Refresh when expired
curl -X POST https://platform.parallel.ai/getServiceKeys/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=$REFRESH_TOKEN"

# 6. Revoke on sign-out
curl -X POST https://platform.parallel.ai/getServiceKeys/token/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "refresh_token=$REFRESH_TOKEN"