Create an account-scoped session

post

https://api.wingspan.app/v3/platform/accounts/{accountId}/sessions

Create an account-scoped session token for the given Account (service-account / embedded flows). No credentials in the body — the caller is already authenticated. Restricted to ServiceAccount principals; an ordinary user bearer is rejected with 403 (fail-closed). X-Wingspan-Account is required and must equal the path accountId.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

accountId

string

required

^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Account identifier. Newly created V3 Accounts use a 22-character Wingspan ID; migrated Accounts may retain a 24-character lowercase Mongo ObjectId.

Body Params

Options for an Account-scoped session created by a ServiceAccount (POST /platform/accounts/{accountId}/sessions). No credentials in the body — the caller authenticates as the ServiceAccount; the session's principal is the target Account (no Person).

expiresAt

date-time

Optional explicit expiry. It must be in the future and no more than one hour from creation; otherwise the request returns 422.

shouldIncludeDescendants

boolean

When true, the session may also act on descendant Accounts of the bound Account (subtree), mirroring accountScope.shouldIncludeDescendants. Default false (this Account only).

Headers

Idempotency-Key

string

length between 1 and 255

^[\x21-\x7e]{1,255}$

Optional idempotency token for authenticated POST and PATCH requests. Reusing the same key and body returns the cached response for 24 hours, except credential operations that explicitly document a 409 because one-time secret material is never cached; reusing it with a different body returns 409 IdempotencyKeyConflict. Use 1-255 printable ASCII characters.

X-Wingspan-Account

string

required

^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Must equal the path accountId and be authorized for the ServiceAccount.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

201Account-scoped session created

400Malformed request syntax

401Unauthenticated

403Forbidden

404Resource not found

422Validation error