Poll a device authorization - Spacefast Docs

Poll a device authorization

Returns the status of the device authorization behind deviceCode, and on the one poll that answers approved, the minted API key with its one-time secret. Wait at least interval seconds between polls: a faster poll answers 429 slow_down, and five consecutive fast polls invalidate the device code. Every later poll answers consumed and never returns the secret again.

POST `/v1/auth/device/poll`

Request body

required application/json

deviceCode string required

deviceCode from the start response. Send it in the body only, never in a URL.

min length 1 · max length 512

Responses

200 Response for status 200

$schema string

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

data object required

Show properties Hide properties

`access` object

Scopes and team access the approver granted. Present alongside apiKey.

Show properties Hide properties

profile string | any required

Access profile whose scope set exactly matches what was granted. Null once the approver changed the set.

scopes string[] required

Scopes the approver granted. These, not profile, say what the key can do.

min items 1

teams object required

Teams the key may act in: all for every team the approver belongs to, including teams joined later, teams for the listed ones, none for sign-in only.

Show properties Hide properties

teamIds string[] required

Teams the credential may act in. Each team appears once.

min items 1 · max items 100

`apiKey` object

Minted API key, carrying its one-time secret. Present only on the poll that answers approved.

Show properties Hide properties

collection string required

team for a key acting on the owning team's own resources, partner for a key acting on customer resources that team manages.

Allowed: team partner

createdAt string required

ISO 8601 timestamp when the key was created.

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:.\d+)?)?(?:Z))$

createdByUserId string required

User account that created the key.

enabled boolean required

False once the key is revoked, which stops it authenticating.

expiresAt string | any required

ISO 8601 timestamp from which requests presenting the key are rejected. Null when it does not expire.

id string required

API key ID (key_ prefix).

ipAllowlist string[] | any required

Exact IP addresses and IPv4 CIDR ranges the key may be used from. Null when any address is allowed.

lastRequestAt string | any required

ISO 8601 timestamp of the most recent request made with the key. Null until it is used.

metadata object required

Metadata stored with the key when it was created or last updated.

name string | any required

Name given to the key. Null when it was created without one.

notBefore string | any required

ISO 8601 timestamp before which requests presenting the key are rejected. Null when it works from creation.

ownerPrincipal object | any required

Principal that owns the key. Ownership only: what the key may do comes from policy. Null on platform-owned keys.

type string required

team when a team owns the key, external when an external customer does.

Allowed: team external

id string required

Identifier of the owning team or external customer.

min length 1

policy object | any required

Policy the key authorizes by. Null on a device login key, whose authority is recompiled from the holder's live team roles on every request.

statements object[] required

Statements evaluated on every request. A matching deny refuses it, otherwise a matching allow permits it, otherwise it is refused.

min items 1

actions string[] required

Actions this statement applies to.

min items 1

conditions object

Attributes that must all hold for the statement to match. An attribute the server cannot resolve fails closed: it blocks an allow and triggers a deny. - request.client string

Narrows the statement to requests the server resolves to this client. Omit to apply it to every client.

Allowed: dashboard cli api worker

effect string required

allow permits the listed actions, deny refuses them. A matching deny beats every allow.

Allowed: allow deny

resources string[] required

Resources this statement applies to.

min items 1

version string required

Policy format version. Any other value is rejected.

preset string | any required

Named permission bundle the key is labeled with. Null when it was created from an explicit policy or permission list.

revokedAt string | any required

ISO 8601 timestamp when the key was revoked. Null while it is still usable.

secret string

The key's secret in full, sfa_ followed by 56 characters. Present only in the response that created the key.

secretPreview string required

Masked form of the secret: its first eight characters and its last four, joined by three dots.

subject object | any required

What the key acts as in audit records.

type string required

What the key acts as: a user, a team, an external customer, or Spacefast itself as system.

Allowed: user team external system

id string required

Identifier of the subject the key acts as.

min length 1

teamScope object | any required

Teams a device login key follows the holder's membership in. Null on a key that authorizes by a fixed policy.

teamIds string[] required

Teams the credential may act in. Each team appears once.

min items 1 · max items 100

updatedAt string required

ISO 8601 timestamp of the last change to the key.

claimedSpaceId string | any

Space claimed during approval. Null when the flow carried no claim.

status string required

One of pending (nobody has approved or denied it yet), approved (returned on the one poll that hands over the API key), consumed (the key was already handed over), denied (the person refused), expired (the codes lapsed or the device polled too fast).

Allowed: pending approved denied expired consumed

defaultError.

Every 4xx and 5xx response is one RFC 9457 problem document served as application/problem+json.

`$schema` string

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

type string required

URL of the documentation page for this error. Derived from code.

title string required

Human-readable name of the error type. Derived from code.

status integer required

HTTP status of the response, repeated in the body.

min -9007199254740991 · max 9007199254740991

detail string required

What went wrong in this request.

code string required

Stable snake_case error code. Match on this, not on detail.

pointer string

RFC 6901 JSON Pointer to the request field or batch entry that failed, for example /files/37/path. Present on validation failures.

details object

Machine-readable context keyed by the error code.

suggestions string[]

Recovery steps safe to show to a person.

next string[]

Commands or API requests to run next, usable as written.

requestId string required

ID of this request, from the X-Request-Id header or generated. Quote it when contacting support.

Try it

Server

Base URL https://api.spacefast.com

Custom base URL Overrides the selected server when set.

Body application/json

deviceCode string* deviceCode from the start response. Send it in the body only, never in a URL.

Send

Request

cURL

curl -X POST "https://api.spacefast.com/v1/auth/device/poll" \
  -H "Content-Type: application/json" \
  -d '{\n  "deviceCode": "string"\n}'

JavaScript

const response = await fetch("https://api.spacefast.com/v1/auth/device/poll", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: "{\n  \"deviceCode\": \"string\"\n}"
});

Python

import requests

response = requests.post(
    "https://api.spacefast.com/v1/auth/device/poll",
    headers={
        "Content-Type": "application/json"
    },
    data="{\n  \"deviceCode\": \"string\"\n}",
)

Response

200 default

{
  "$schema": "http://example.com",
  "data": {
    "access": {
      "profile": "read",
      "scopes": [
        "teams:read"
      ],
      "teams": {}
    },
    "apiKey": {
      "collection": "team",
      "createdAt": "2019-08-24T14:15:22Z",
      "createdByUserId": "string",
      "enabled": true,
      "expiresAt": "2019-08-24T14:15:22Z",
      "id": "string",
      "ipAllowlist": [
        "string"
      ],
      "lastRequestAt": "2019-08-24T14:15:22Z",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "name": "string",
      "notBefore": "2019-08-24T14:15:22Z",
      "ownerPrincipal": {
        "type": "team",
        "id": "string"
      },
      "policy": {
        "statements": [
          {
            "actions": [
              "spaces:read"
            ],
            "conditions": {
              "request.client": "dashboard"
            },
            "effect": "allow",
            "resources": [
              "string"
            ]
          }
        ],
        "version": "2026-06-09"
      },
      "preset": "ci_deploy",
      "revokedAt": "2019-08-24T14:15:22Z",
      "secret": "string",
      "secretPreview": "string",
      "subject": {
        "type": "user",
        "id": "string"
      },
      "teamScope": {},
      "updatedAt": "2019-08-24T14:15:22Z"
    },
    "claimedSpaceId": "string",
    "status": "pending"
  }
}

Error Response

{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}

Poll a device authorization

POST /v1/auth/device/poll

Request body

Responses

200 Response for status 200

access object

apiKey object

defaultError.

$schema string

Try it

Server

Body application/json

Send

Request

cURL

JavaScript

Python

Response

200 default

Error Response

POST `/v1/auth/device/poll`

`access` object

`apiKey` object

`$schema` string