Enrollment (DPoP)

The flash API has two authentication modes. This page covers enrollment + DPoP; for the API key mode, see API authentication. Enrollment gives the client a per-installation identity:

The API key is used once to enroll the installation.
The client creates an ES256 (P-256) key pair inside a platform secure store. The private key stays there; the app only gets the public JWK and a signing handle.
The client receives a 15-minute access token and a 30-day refresh token.
Every data request presents Authorization: DPoP <access-token> plus a DPoP proof header.

Choose enrollment when the app is distributed across user machines, when a leaked API key should not be enough to act as an existing installation, or when you need to revoke one machine without revoking the whole key. For a simple internal tool, the API key mode is usually enough.

One API key can have at most 3 active installations. Revoke an old installation before enrolling a replacement.

Flow

1. Request a challenge

POST /api/saas/v1/flash/enroll/challenge
Authorization: Bearer fng_pat_...

{
  "data": {
    "challenge": "…",
    "expires_at": "2026-11-04T10:10:00Z"
  }
}

The challenge is single-use and expires after five minutes.

2. Enroll the installation

Sign SHA-256(challenge) with the installation private key inside the secure store, then send the public JWK and signature.

POST /api/saas/v1/flash/enroll
Authorization: Bearer fng_pat_...
Content-Type: application/json

{
  "challenge": "…",
  "public_key_jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "…",
    "y": "…"
  },
  "signature": "…",
  "app_name": "flash-tool",
  "app_version": "1.0.0",
  "build_hash": "…",
  "os": "your-os",
  "machine_hash": "…"
}

signature is the ES256 signature over SHA-256(challenge), base64url or standard base64. public_key_jwk must be an EC P-256 key.

{
  "data": {
    "installation_id": "…",
    "status": "active",
    "access_token": "…",
    "token_type": "DPoP",
    "expires_in": 900,
    "refresh_token": "…"
  }
}

The refresh token is returned once. Store it in the same platform secure store.

3. Call data endpoints

GET /api/saas/v1/flash/firmwares
Authorization: DPoP <access-token>
DPoP: <proof-jwt>

The proof is an ES256 JWT with:

Claim	Value
`htm`	HTTP method, for example `GET`
`htu`	Full public URL without query, for example `https://api.firmngin.dev/api/saas/v1/flash/firmwares`
`iat`	Current Unix time; accepted within 60 seconds
`jti`	Unique proof id
`ath`	Base64url SHA-256 of the access token

The proof header must include typ: "dpop+jwt" and the installation public key in jwk. The htu must match the public URL the API sees; when the API runs behind a proxy, set URL_BACKEND so the expected URL matches. The private key never leaves the client; only the public JWK is sent.

4. Refresh

POST /api/saas/v1/flash/token
Content-Type: application/json
DPoP: <proof-jwt>

{ "refresh_token": "…" }

The refresh request uses a DPoP proof without ath. Refresh tokens rotate on every use; reusing an old token revokes the whole family.

5. Manage installations

GET /api/saas/v1/flash/installations
Authorization: Bearer fng_pat_...

POST /api/saas/v1/flash/installations/{id}/revoke
Authorization: Bearer fng_pat_...

Revoking an installation invalidates its access tokens (checked on the next request) and its refresh tokens.

Getting started

Devices

Firmware

AI & automation

Billing

Fleet Batches

Device Billing

Libraries

Enrollment (DPoP)

Flow

1. Request a challenge

2. Enroll the installation

3. Call data endpoints

4. Refresh

5. Manage installations

​Flow

​1. Request a challenge

​2. Enroll the installation

​3. Call data endpoints

​4. Refresh

​5. Manage installations

Flow

1. Request a challenge

2. Enroll the installation

3. Call data endpoints

4. Refresh

5. Manage installations