Collect the token once the person approved

POST

/v1/device/token

curl --request POST \
  --url https://api.eu.apigami.com/v1/device/token \
  --header 'Content-Type: application/json' \
  --data '{ "device_code": "example" }'

• Production, EU (Frankfurt)

Held up to 25 s while the person has not decided, and answered as soon as they do. Poll again after interval seconds, counted from the previous answer: earlier is slow_down, which adds 5 s to the interval, up to 60. The token is delivered once, and stays collectable for 15 minutes after the approval. It lasts 90 days and opens /mcp and the author routes of the team; never a management route. Write it into your MCP client’s settings for your user, never a project file, and never print it.

Request Body^required

Media typeapplication/json

object

device_code

required

string

Example^generated

{
  "device_code": "example"
}

Responses

200

The person approved. Answered once per request.

Media typeapplication/json

object

access_token

required

apigami_agent_ followed by 46 characters.

string

token_type

required

string

Allowed values: Bearer

expires_in

required

Seconds: 90 days.

integer

email

required

The account you now act for.

string

mcp_url

required

string format: uri

mcp_headers

required

The headers any MCP client sends to mcp_url.

object

key

additional properties

string

docs_url

required

The settings of each MCP client.

string format: uri

message

required

string

Example

{
  "token_type": "Bearer"
}

400

Not yet, or never. authorization_pending and slow_down carry the interval to wait. access_denied: the person refused; do not start again unless they ask. expired_token: no decision in 15 minutes, or not collected within 15 minutes of the approval; start again. invalid_grant: unknown device_code, or a token already collected; do not retry.

Media typeapplication/json

object

error

required

string

Allowed values: invalid_request authorization_pending slow_down access_denied expired_token invalid_grant too_many_requests

error_description

required

What to do next, in English.

string

interval

With authorization_pending and slow_down: the seconds to wait before polling again.

integer

Examples

{
  "error": "authorization_pending",
  "error_description": "The user has not decided yet. Poll again in 5 s; the link expires at 2026-10-07T14:17:00.000Z.",
  "interval": 5
}

{
  "error": "slow_down",
  "error_description": "Polling too fast: wait 10 s between requests.",
  "interval": 10
}

{
  "error": "access_denied",
  "error_description": "The user refused. Do not start again unless they ask you to."
}

{
  "error": "expired_token",
  "error_description": "This request expired. Start again with POST /v1/device/code and give the user the new link."
}

{
  "error": "invalid_grant",
  "error_description": "Unknown device_code, or its token was already collected. Do not retry it."
}

429

Too many unknown device_code from this network, with Retry-After.

Media typeapplication/json

object

error

required

string

Allowed values: invalid_request authorization_pending slow_down access_denied expired_token invalid_grant too_many_requests

error_description

required

What to do next, in English.

string

interval

With authorization_pending and slow_down: the seconds to wait before polling again.

integer

Example

{
  "error": "too_many_requests",
  "error_description": "Too many agent sign-in requests from this network. Retry after 60 s. Meanwhile keep polling the request you already have instead of opening a new one."
}