API Reference

Create a ServiceAccount

post
https://api.wingspan.app/v3/platform/service-accounts

Creates a machine identity owned by an Account or Organization. Permissions come from the ServiceAccount's custom owner roleId and explicitly approved supplemental scopes. Duplicate externalId values return 409 ResourceConflict; create is not an upsert.

Requires a session with recent MFA step-up for ApiKeyChange. If step-up is missing or expired, this operation returns 403 StepUpMfaRequired; create and verify an MFA challenge at /v3/platform/mfa-challenges with requiredFor: "ApiKeyChange", then retry.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
enum
required

Whether the ServiceAccount is owned by an Account (most common — scoped programmatic identity for one regulated entity) or an Organization (cross-Account machine identity for an enterprise / Embed customer with multiple Accounts).

Allowed:
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.

string
required
string
string
^role_[a-zA-Z0-9_-]+$

Optional RBAC Role reference for the new ServiceAccount.

scopes
array of strings

Direct supplemental machine capability scopes, action-qualified as domain.resource:read or domain.resource:write (for example payments.payable:write). Additive on top of any roleId.

scopes
string
metadata
object

Free-form key-value pairs. Max 50 keys; key length at most 40 characters; value length at most 500 characters. Where a list endpoint declares metadata filtering, it uses the QueryQL namespace via filter[metadata.{key}][eq]=value or filter[metadata.{key}][in][]=value. Endpoints that do not declare the dynamic Metadata filter do not support Metadata filtering.

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

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

string
length between 1 and 255

Deduplicates ServiceAccount creation. The key is reserved within the selected owner for the lifetime of the created ServiceAccount; the same key and body replay the original response, while a changed body returns 409.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated 4 months ago

Did this page help you?
Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json

Updated 4 months ago

Did this page help you?