Create API key

import requests

url = "https://api.example.com/api/v1/api-keys"

payload = {
    "name": "<string>",
    "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "scopes": ["<string>"],
    "expires_at": "2023-11-07T05:31:56Z"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.example.com/api/v1/api-keys \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scopes": [
    "<string>"
  ],
  "expires_at": "2023-11-07T05:31:56Z"
}
'

{
  "result": {
    "api_key": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key_prefix": "<string>",
      "scopes": [
        "<string>"
      ],
      "expires_at": "2023-11-07T05:31:56Z",
      "last_used_at": "2023-11-07T05:31:56Z",
      "is_revoked": true,
      "revoked_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "pact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "raw_key": "<string>"
  },
  "success": true,
  "suggestion": "",
  "message": "",
  "meta": {
    "total": 123,
    "offset": 123,
    "limit": 123,
    "has_more": true,
    "after": "<string>",
    "before": "<string>"
  }
}

{
  "result": {
    "api_key": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key_prefix": "<string>",
      "scopes": [
        "<string>"
      ],
      "expires_at": "2023-11-07T05:31:56Z",
      "last_used_at": "2023-11-07T05:31:56Z",
      "is_revoked": true,
      "revoked_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "pact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "raw_key": "<string>"
  },
  "success": true,
  "suggestion": "",
  "message": "",
  "meta": {
    "total": 123,
    "offset": 123,
    "limit": 123,
    "has_more": true,
    "after": "<string>",
    "before": "<string>"
  }
}

{
  "success": false,
  "error": {
    "detail": [
      {
        "loc": [
          "<string>"
        ],
        "msg": "<string>",
        "type": "<string>",
        "input": "<unknown>",
        "ctx": {}
      }
    ]
  }
}

Identity

Create API key

This operation creates a new API key for a principal.

When authenticated with a principal API key, the new key is created for the authenticated principal. When authenticated with a service credential, principal_id is required.

Use scopes to restrict what the key can access. The default scope ["*"] grants full access. Individual scopes use the format resource:action where action is read, write, or status. For example: ["wallet:read", "wallet:write"].

Supply expires_at to set an expiry time. If omitted, the key does not expire.

The raw API key value is only returned once in the response. Store it securely — it cannot be retrieved again.

POST

api

api-keys

Create API key

import requests

url = "https://api.example.com/api/v1/api-keys"

payload = {
    "name": "<string>",
    "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "scopes": ["<string>"],
    "expires_at": "2023-11-07T05:31:56Z"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.example.com/api/v1/api-keys \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scopes": [
    "<string>"
  ],
  "expires_at": "2023-11-07T05:31:56Z"
}
'

{
  "result": {
    "api_key": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key_prefix": "<string>",
      "scopes": [
        "<string>"
      ],
      "expires_at": "2023-11-07T05:31:56Z",
      "last_used_at": "2023-11-07T05:31:56Z",
      "is_revoked": true,
      "revoked_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "pact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "raw_key": "<string>"
  },
  "success": true,
  "suggestion": "",
  "message": "",
  "meta": {
    "total": 123,
    "offset": 123,
    "limit": 123,
    "has_more": true,
    "after": "<string>",
    "before": "<string>"
  }
}

{
  "result": {
    "api_key": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "key_prefix": "<string>",
      "scopes": [
        "<string>"
      ],
      "expires_at": "2023-11-07T05:31:56Z",
      "last_used_at": "2023-11-07T05:31:56Z",
      "is_revoked": true,
      "revoked_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "pact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "raw_key": "<string>"
  },
  "success": true,
  "suggestion": "",
  "message": "",
  "meta": {
    "total": 123,
    "offset": 123,
    "limit": 123,
    "has_more": true,
    "after": "<string>",
    "before": "<string>"
  }
}

{
  "success": false,
  "error": {
    "detail": [
      {
        "loc": [
          "<string>"
        ],
        "msg": "<string>",
        "type": "<string>",
        "input": "<unknown>",
        "ctx": {}
      }
    ]
  }
}

Headers

X-API-Key

string | null

X-Assistant-Service-Key

string | null

Body

application/json

Request payload for creating an API key.

name

string

required

The display name for this API key. Max 255 characters.

Maximum string length: 255

principal_id

string<uuid> | null

The ID of the principal to create the API key for. Required when using service credential authentication; ignored when using principal API key authentication.

scopes

string[]

The access scopes for this key. Use ["*"] for full access, or restrict with resource:action format (for example, ["wallet:read", "wallet:write"]). Possible actions: read, write, status.

expires_at

string<date-time> | null

The expiry timestamp for this key, in ISO 8601 format. If omitted, the key does not expire.

Response

Already exists (idempotent). Successful Response

result

ApiKeyCreateResultPublic · object

required

Create API key result payload without delegation internals.

Show child attributes

success

boolean

default:true

suggestion

string

default:""

message

string

default:""

General

CLI

API reference

Create API key

Headers

Body

Response