Skip to content
ApiqDevelopers
API v1.64.0Open console
API referenceidentity

Poll device signup

POST/v1/signup/device:token

Poll a device-code sign-up — pending, slow down, or the new tenant with its sandbox key

The agent polls with the device_code of POST /v1/signup/device.Show moreThe agent polls with the device_code of POST /v1/signup/device. Until the person decides it is 400 OAuthError authorization_pending; polling faster than interval is slow_down (add 5 s to the interval, RFC 8628 section 3.5); a request not approved within 15 minutes is expired_token; a denied request, or one cancelled because it was approved with another e-mail (reason EMAIL_MISMATCH), is access_denied; an unknown device_code, or one already redeemed, is invalid_grant. It never carries session: no Owner session reaches the agent; the person signs in to the console themselves (the e-mailed code, or a password they set). A request whose e-mail, once proven, belongs to a domain that already has a tenant was REFUSED at approval: the poll answers 409 CONFLICT details.reason TENANT_EXISTS (nextAction request_invite) and the device_code is spent. The 400s speak RFC 6749 section 5.2 OAuthError (as POST /v1/oauth/token), because a device-flow client parses {error}; the 409 and the 5xx are ApiErrorResponse. MCP: excluded.

Request bodyDeviceSignupTokenRequest

  • device_codestringRequired

Responses

  • 200Approved — the new tenant and its sandbox key, the MCP endpoint and the manifest; never a sessionDeviceSignupResult
  • 400
    RFC 8628 section 3.5 — authorization_pending (keep polling), slow_down (poll 5 s slower), expired_token (start again), access_denied (the person denied, or the request was cancelled), invalid_grant…Show moreRFC 8628 section 3.5 — authorization_pending (keep polling), slow_down (poll 5 s slower), expired_token (start again), access_denied (the person denied, or the request was cancelled), invalid_grant (an unknown or spent device_code), or invalid_request (no device_code)
    OAuthError
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 409
    CONFLICT TENANT_EXISTS — the e-mail was proven and its domain already has a tenant; the request was REFUSED and nothing was created.Show moreCONFLICT TENANT_EXISTS — the e-mail was proven and its domain already has a tenant; the request was REFUSED and nothing was created. Ask that tenant's Owner for an invite (nextAction request_invite); the Owner has been notified (signup.tenant_exists).
    ApiErrorResponse
  • 413
    VALIDATION — the request body is larger than the surface's limit.Show moreVALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 415
    VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show moreVALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501NOT_IMPLEMENTED DEVICE_SIGNUP_UNAVAILABLE — device-code sign-up is off on this deploymentApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

405VALIDATION
This method is not served.
not retryable
409CONFLICT
An account already exists for skyhop.example. Ask its Owner to invite you.
not retryable
413VALIDATION
The request body is larger than this API accepts (262144 bytes).
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
415VALIDATION
Send application/json.
not retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
Device-code sign-up is not available on this deployment.
not retryable