FleetDeckDocs

API reference / Dashboard keys

Create a scoped key

Create a key for selected accessible, entitled phones.

POST/api/agent-keys

Authorization

Dashboard sessionDashboard session cookie + same Origin

Use your signed-in dashboard session cookie. A FleetDeck API key cannot authenticate this endpoint. Browser requests must be same-origin; write requests require a matching Origin header. Authentication guide ↗

Request example
Request · cURL
curl --request POST \
  --url 'https://fleetdeck.co/api/agent-keys' \
  --cookie "$FLEETDECK_DASHBOARD_COOKIE" \
  --header 'Origin: https://fleetdeck.co' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My agent",
  "scopes": [
    "devices:read"
  ],
  "deviceIds": [
    "device_123"
  ],
  "expiresInDays": null
}'

Replace example IDs with returned values. Read credentials from your private environment.

Response examples
200 · success
{
  "id": "key_123",
  "name": "My agent",
  "prefix": "fd_example",
  "scopes": [
    "devices:read"
  ],
  "deviceIds": [
    "device_123"
  ],
  "expiresAt": null,
  "revokedAt": null,
  "createdAt": "2030-01-01T10:00:00.000Z",
  "token": "<shown once; save securely>"
}

Required headers

Originstringrequired

Must match this app’s origin or configured public app origin.

uri
Example: "https://fleetdeck.co"

Request body application/json

namestringrequired

Name of the resource or operation. For commands with an enum, choose one of the listed values.

min 1 charactersmax 80 characters
Example: "My agent"
scopesstring[]required

Permissions granted to the key. Operations can require more than one scope.

min 1 itemsmax 6 items
deviceIdsstring[]required

Exact IDs of the devices this key may access.

min 1 itemsmax 100 items
expiresInDaysinteger | nulloptional

Integer 1..365 for a finite lifetime; null for no expiry. Omission defaults to 30 days. Does not change session, job or child-token expiration.

min 1max 365default 30

Unknown fields are rejected.

Behavior and limits

Create a key for selected accessible, entitled phones. name is 1..80 trimmed characters; scopes has 1..6 entries from the scope list; deviceIds 1..100; expiresInDays accepts an integer 1..365 or null for no expiry; omission defaults to 30 days. The response expiresAt is an ISO timestamp or null for no expiry. No-expiry keys remain revocable and subject to device grants, account access and entitlement checks; they do not make sessions, job leases or child credentials permanent. Maximum 50 active keys per user, including nonrevoked no-expiry keys. Request body limit is 16,384 bytes. Token is returned once: save it securely. Prefer the /agents dashboard.

Response 200

CreatedKey · application/json

idstringalways present

Unique identifier of this resource. Use the returned value in subsequent requests.

min 1 charactersmax 128 characters
Example: "key_123"
Validation pattern^[A-Za-z0-9._:-]+$
namestringalways present

Name of the resource or operation. For commands with an enum, choose one of the listed values.

Example: "My agent"
prefixstringalways present

Nonsecret token prefix for identifying a key in the dashboard.

Example: "fd_example"
scopesstring[]always present

Permissions granted to the key. Operations can require more than one scope.

deviceIdsstring[]always present

Exact IDs of the devices this key may access.

expiresAtstring | nullalways present

Null means no expiry for this user-created key. The key remains revocable. Session and job-child expirations remain finite.

date-time
revokedAtstring | nullalways present

UTC instant the key was revoked, or null while it has not been revoked.

date-time
createdAtstringalways present

UTC instant when the record was created.

date-time
Example: "2030-01-01T10:00:00.000Z"
tokenstringalways present

Secret shown once. Save securely; cannot be retrieved later.

Example: "<shown once; save securely>"

Errors

Expand a code for its recovery steps. Responses use error and code; validation errors also include issues.

401UNAUTHORIZEDMissing, malformed, expired or revoked credential; user verification/password state can also deny access.

Recovery: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.

Full error reference ↗
403FORBIDDENRequired scope, device grant, account membership or worker identity is missing.

Recovery: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.

Full error reference ↗
404NOT_FOUNDUnknown route or resource unavailable to this caller.

Recovery: Check method/path and use returned IDs from this account/key. Do not guess IDs.

Full error reference ↗
402PLAN_REQUIREDDevice account has no active entitlement.

Recovery: Restore an active device entitlement in the workspace before controlling it.

Full error reference ↗
403ORIGINDashboard mutation lacks an allowed Origin header.

Recovery: Use the signed-in same-origin dashboard. Cross-origin key management is not supported.

Full error reference ↗
409LIMITMaximum 50 active keys per user or 100 queued jobs per key.

Recovery: Revoke unused keys or cancel unnecessary queued jobs before creating more.

Full error reference ↗
400INVALID_JSONMissing or malformed JSON.

Recovery: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.

Full error reference ↗
415CONTENT_TYPEA supplied JSON body lacks application/json content type.

Recovery: Set Content-Type: application/json; charset parameters are accepted.

Full error reference ↗
413TOO_LARGERequest body exceeds its byte limit.

Recovery: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.

Full error reference ↗
422VALIDATIONA field, type, bound or unknown property failed validation.

Recovery: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.

Full error reference ↗
500INTERNALUnexpected service error.

Recovery: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.

Full error reference ↗

Example error messages are illustrative. Match the code and HTTP status; do not depend on exact message wording.