Get a token

POST/oauth/token

Exchanges an authorization code for an access token and a refresh token, or a refresh token for a new pair. The access token works as a bearer token on Call the MCP server and on every other API endpoint, like an API key.

Scope	Heavy call	Long poll	CLI
None, no key	No	No	None

Guidance

It lives at the root of https://api.chartnaut.com, not under /v1. The body is form-encoded, not JSON.
An access token (cn_oat_) lasts 1 hour. Before it runs out, or on a 401 from the API, swap the refresh token (cn_ort_) for a new pair. Each swap starts the refresh token's 30 days again.
Every refresh returns a new refresh token and ends the old one. Store the new one straight away. Presenting an old refresh token again more than 30 seconds after the swap ends the whole connection, and the person has to approve your app again. Within those 30 seconds, a repeat gets another pair, so two requests racing each other are safe. A refresh does not end access tokens already issued; each works until its own hour is up.
An access token acts as the person, with the scopes they approved, and passes the same plan, request-budget and scope checks as an API key. On Free every call with it gets 403 plan_limit.
Errors use OAuth's shape, {"error": "...", "error_description": "..."}. Every answer carries Cache-Control: no-store.
Limited to 60 a minute from one IP address, shared with Revoke a token.

Request body

application/x-www-form-urlencoded, up to 64 KB. client_id can also come as the user name in HTTP Basic auth.

authorization_code

Field	Type	Required	Description
`grant_type`	string	Yes	`authorization_code`
`code`	string	Yes	From the redirect, within 60 seconds
`redirect_uri`	string	Yes	The exact `redirect_uri` the authorization used
`code_verifier`	string	Yes	The PKCE verifier behind the `code_challenge`
`client_id`	string	Yes	The client the code was issued to
`resource`	string	No	`https://api.chartnaut.com/v1/mcp`

refresh_token

Field	Type	Required	Description
`grant_type`	string	Yes	`refresh_token`
`refresh_token`	string	Yes	The latest refresh token
`client_id`	string	No	Checked against the connection when sent
`scope`	string	No	Space-separated. Only scopes already granted
`resource`	string	No	`https://api.chartnaut.com/v1/mcp`

Response

200 with:

Field	Type	Description
`access_token`	string	`cn_oat_` and 64 hex characters
`token_type`	string	`Bearer`
`expires_in`	integer	Seconds: 3600
`refresh_token`	string	`cn_ort_` and 64 hex characters
`scope`	string	The granted scopes, space-separated

Status codes

Status	Code	Meaning
`200`	-	A new access token and refresh token
`400`	`invalid_request`	A required field is missing, or the body is not form-encoded
`400`	`invalid_grant`	The code or refresh token is wrong, expired, already used, or issued to another client; the `redirect_uri` or `code_verifier` does not match; or the connection was revoked. Start a new authorization
`400`	`invalid_scope`	`scope` asks for more than was granted
`400`	`invalid_target`	`resource` is not the MCP server
`400`	`unsupported_grant_type`	Not `authorization_code` or `refresh_token`
`401`	`invalid_client`	Unknown `client_id`
`429`	`temporarily_unavailable`	More than 60 in a minute from your IP address
`500`	`server_error`	Retry

Example request

curl https://api.chartnaut.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=cnc_5f2a9c0e7b3d41a8e6c19f04b7d2a3e1 \
  -d code=8f14e45fceea167a5a36dedd4bea2543c9f0f895fb98ab9159f51fd0297e236d \
  -d redirect_uri=http://127.0.0.1:33418/callback \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk \
  -d resource=https://api.chartnaut.com/v1/mcp

Example response

200 OK

{
  "access_token": "cn_oat_XXXX",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "cn_ort_XXXX",
  "scope": "scripts:read scripts:write runs:write"
}

400 Bad Request

{
  "error": "invalid_grant",
  "error_description": "authorization code expired"
}

From the CLI

There is no CLI command for this endpoint. The CLI uses an API key from Poll a sign-in instead.