Offline access device flow

Use the device flow to obtain an offline-access token bundle for the principal in the caller's consumer token. The service handles its confidential OAuth client credentials; callers never send a client secret to BigFS.

Routes

Route	Required fields	Optional fields	Result
ANY /v1/offline_access/oauth/device/issue	—	scope, aud, label	Starts a device authorization flow.
ANY /v1/offline_access/oauth/device/pickup	id	—	Returns the pending, success, or terminal state.

Both routes require a consumer token. A caller may pick up only an offline access record owned by that token's principal.

Start a device flow

Call /v1/offline_access/oauth/device/issue to receive the user-facing verification information. scope defaults to openid profile email groups offline_access when omitted or empty. aud is optional. label is a caller label stored with the request.

Field	Required	Type	Description
scope	No	String	Requested OAuth scopes.
aud	No	String	Requested audience.
label	No	String	Human-readable label for the request.

curl -sS https://api.bigfs.m7.org/v1/offline_access/oauth/device/issue \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"label":"Desktop backup"}'

{
  "status": 1,
  "data": {
    "id": "OFFLINE_ACCESS_UUID",
    "status": "pending",
    "user_code": "ABCD-EFGH",
    "verification_uri": "https://sso.user.m7.org/device_login",
    "verification_uri_complete": "https://sso.user.m7.org/device_login?user_code=ABCD-EFGH",
    "expires_in": 600,
    "interval": 5
  }
}

Show the verification URL and code to the user. Do not expose the service's OAuth client credentials.

Pick up the result

Poll /v1/offline_access/oauth/device/pickup with the returned id. Wait at least the returned interval seconds between requests. A slow_down response returns a larger interval, which replaces the previous polling interval.

Field	Required	Type	Description
id	Yes	UUID	Offline-access record ID from issue.

Pending example:

{
  "status": 1,
  "data": {
    "id": "OFFLINE_ACCESS_UUID",
    "status": "pending",
    "interval": 5,
    "comment": "authorization pending"
  }
}

Completed example:

{
  "status": 1,
  "data": {
    "id": "OFFLINE_ACCESS_UUID",
    "status": "success",
    "token_type": "bearer",
    "access_token": "ACCESS_TOKEN",
    "expires_in": 900,
    "refresh_token": "REFRESH_TOKEN",
    "refresh_expires_in": 2592000,
    "binding_chain": "BINDING_CHAIN",
    "binding_link": "BINDING_LINK",
    "scope": "openid profile email groups offline_access"
  }
}

Store the returned access token, refresh token, binding_chain, and binding_link securely as one package. A provider refresh requires the full package and the owning OAuth client's authentication; BigFS does not expose a public refresh route. Terminal failures return status: "error" with one of access_denied, expired_token, or the OAuth error reported by the provider. Re-picking up a completed record returns status: "success" without token values; retain the package from the first successful response.