API reference

Create API key

Create a scoped subkey for the same API account. Review Diffio API behavior, response fields, setup details, and production workflows.

Create a least privilege scoped API key with an admin-capable key.

POST/v1/api_keys/createPermissions: admin, keys:write

Endpoint

HTTP request

https://api.diffio.ai/v1/api_keys/create

Use POST with a JSON body.

Permissions

admin, keys:write

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>

Request

Provide a label, scopes, and optional resource bounds for the new scoped key.

Body fields

Field	Type	Required	Description
`label`	string	Yes	Human-readable key label, 80 characters or fewer.
`scopes`	array	Yes	Scopes granted to the new key.
`resourceBounds`	object	No	Optional resource bounds stored with the key.

cURL

curl -X POST "https://api.diffio.ai/v1/api_keys/create" \  -H "Authorization: Bearer $DIFFIO_AGENT_KEY" \  -H "Content-Type: application/json" \  -d '{    "label": "Dashboard browser key",    "scopes": [      "projects:read",      "projects:write",      "generations:read",      "generations:write",      "artifacts:read"    ],    "resourceBounds": {      "projectIds": ["proj_123"]    }  }'

Response

Returns the new key metadata plus the plaintext key once.

Response fields

Field	Type	Required	Description
`key`	string	Yes	Plaintext API key secret. It is returned only in this response.
`keyId`	string	Yes	Stored API key document id.
`label`	string	Yes	Stored key label.
`status`	string	Yes	Key status, initially active.
`keyPrefix`	string	Yes	Display-safe prefix for identifying the key.
`role`	string	Yes	Key role, set to scoped.
`scopes`	array	Yes	Scopes granted to the key.
`resourceBounds`	object	Yes	Stored resource bounds, or an empty object.
`parentKeyId`	string	Yes	Admin key that created the scoped key.
`permissions`	object	Yes	Legacy read/write permissions implied by the scopes.

Successful response

{  "key": "diffio_live_child_secret",  "keyId": "key_child_123",  "label": "Dashboard browser key",  "status": "active",  "keyPrefix": "diffio_live_child",  "role": "scoped",  "scopes": [    "projects:read",    "projects:write",    "generations:read",    "generations:write",    "artifacts:read"  ],  "resourceBounds": {    "projectIds": ["proj_123"]  },  "parentKeyId": "key_admin_123",  "createdAt": "2026-05-09T12:00:00Z",  "rotatedAt": null,  "revokedAt": null,  "permissions": {    "read": true,    "write": true  }}

Return codes

200Success, treated as complete.: Scoped API key created.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, label is required, label is too long, scopes are invalid, or resourceBounds must be an object.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: Privileged admin API key required, API key is not active, or missing keys:write permission.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: API key missing userId, or failed to create API key.

Notes

The new key secret is returned once and is stored only as a hash.
The wildcard scope * and billing bypass scopes cannot be created through this endpoint.
The endpoint writes an audit log entry for successful key creation.