Create an API key

Makes a new API key for an account and returns its secret in key. That is the only time the secret is shown: Widgetic keeps a hash, so a key that was not stored cannot be recovered, only replaced. To rotate a key, make the new one, switch the integration over to it, then delete the old one. Only a person signed in on widgetic.com can make a key: a request made with an API key, or with an SDK token, is refused with 403. That way a leaked key cannot be used to make a second one that survives its revocation. Make keys from the dashboard; a key can still list, rename, switch off and delete keys. An Idempotency-Key header is required (8 to 50 characters: letters, digits, - and _). A retry with the same header and the same body returns the same answer instead of making a second key, and the same header with a different body is refused with 422. Make keys one at a time: two requests for the same account that run at the same moment can overwrite each other. A key can be limited to what it needs. Send a preset (read_only, content or full_access) or a list of scopes, never both. Send neither for a key that can do everything its owner can, as every key made before scopes existed. A limited key is refused with 403 and the code API_KEY_SCOPE_MISSING on anything outside its scopes, so a key held by a build server or by a partner’s backend can be given only the part of the API it uses. The scopes of a key are fixed when it is made: to widen one, make a new key and delete the old one. A limited key cannot make, change or delete keys, exchange tokens or reach the administration routes. The list of scopes is in the ApiKeyScope schema. Accounts with API access (Solo, Teams and partner accounts) have no limit on how many keys they hold. An account on a plan without API access cannot make one (a partner account is not asked about a plan).

POST /users/{id}/keys

Create an API key

cURL

curl --request POST \
  --url https://api.widgetic.com/v1/users/{id}/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Production",
  "expiresAt": "2027-01-31T00:00:00Z",
  "preset": "content",
  "scopes": [
    "content:read",
    "generate"
  ]
}
'

200

{
  "success": true,
  "data": {
    "key": "wgt_prt_YOUR_NEW_KEY",
    "keyId": "5f0c1e2a-7a41-4c5e-9f3b-0c2a8b1d6e44",
    "keyPreview": "wgt_prt_ab12...",
    "name": "Production",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "expiresAt": "2026-01-15T09:30:00.000Z",
    "isActive": true,
    "scopes": [
      "Example ApiKeyScope"
    ],
    "preset": "Example preset"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string · required

Required: a call without it is refused with 400. A key of your own that names this one request; a UUID is ideal. It is 8 to 50 characters of letters, digits, - and _. Send the same key again when you retry (after a timeout, a dropped connection or a 5xx) and the call is carried out once: the retry gets the first answer back, marked X-Idempotency-Cached: true. The same key with a different body is refused with 422, and a retry that arrives while the first call is still running with 409 (see Retry-After).

Required string length: 8 - 50

Pattern: ^[a-zA-Z0-9_-]{8,50}$

Example:

"9b2d6f0a-3c41-4e5a-8d77-1f2e3a4b5c6d"

Path Parameters

id · string<uuid> · required

The account the key is for. For your own, your own user id

Body

application/json

name · string · required

A name for the key, to tell it from the account's other keys

Required string length: 1 - 100

Example:

"Production"

expiresAt · string<date-time>

When the key stops working, as a date and time in the future with a zone. Omit it for a key that does not expire

Example:

"2027-01-31T00:00:00Z"

preset · enum<string>

A ready-made list of scopes. read_only looks at everything the account holds and changes nothing. content builds and manages widgets and compositions and runs the AI, and touches no billing, no people and no partners. full_access is the same as sending neither preset nor scopes. Send either preset or scopes, not both

Available options: read_only, content, full_access

Example:

"content"

scopes · enum<string>[]

What the key may do, when a preset is not enough. Naming a write scope includes its read scope, and a list that holds every scope is a key with full access. Send either scopes or preset, not both

Minimum array length: 1

One thing an API key may be allowed to do. A key made with a list of scopes does only what the list names; a key made without one has full access, and does everything its owner can.

• content:read reads widgets, compositions, canvases, projects, folders, uploads, translations and the analytics of your content.
• content:write creates, changes, publishes and deletes the same. It includes content:read.
• generate runs the AI that builds widgets and compositions, and follows or cancels what it is doing. This spends credits.
• partner:read reads managed users, what they spent, presets, the contract and the storage destination.
• partner:write creates, changes and deletes managed users and presets. It includes partner:read.
• billing:read reads credits, usage, invoices, subscriptions and payment methods.
• billing:write buys credits, pays invoices and changes a subscription or a payment method. It includes billing:read.
• account:read reads the profile, organizations and members, allowed domains, notices and the names of API keys.
• account:write changes the profile, organizations and members, allowed domains and integrations. It includes account:read.

Starting an editor session for a managed user needs partner:write, content:write and generate together. Making, changing and deleting keys, exchanging tokens, signing in and the administration routes need full access: a limited key cannot make itself a bigger one.

A request outside the scopes of the key is refused with 403 and the code API_KEY_SCOPE_MISSING. error.details.missingScopes names what a new key needs, and error.details.fullAccessRequired is true when no list of scopes would have been enough. The scopes of a key cannot be changed once it is made.

Available options: content:read, content:write, generate, partner:read, partner:write, billing:read, billing:write, account:read, account:write

Example:

["content:read", "generate"]

Response

200

application/json

The key was made. The secret is in key, and is not shown again

success · boolean · required

Always true on a success.

Example:

true

data · object · required

A key that has just been made. It is the only answer that ever carries the secret, in key. Store it now: Widgetic keeps only a hash of it, and it cannot be shown again.

Show child attributes

Example:

{
  "key": "wgt_prt_YOUR_NEW_KEY",
  "keyId": "5f0c1e2a-7a41-4c5e-9f3b-0c2a8b1d6e44",
  "keyPreview": "wgt_prt_ab12...",
  "name": "Production",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "expiresAt": "2026-01-15T09:30:00.000Z",
  "isActive": true,
  "scopes": ["Example ApiKeyScope"],
  "preset": "Example preset"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes