> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/products/agentic-wallet/manual/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## OpenAPI
````yaml post /api/v1/api-keys
openapi: 3.1.0
info:
title: Cobo Agentic Wallet Service
description: Unified wallet engine for human and agent principals
version: 1.3.0
servers: []
security: []
paths:
/api/v1/api-keys:
post:
tags:
- Identity
summary: Create API key
description: >-
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.
operationId: create_api_key
parameters:
- name: X-API-Key
in: header
required: false
schema:
title: X-Api-Key
type: string
nullable: true
- name: X-Assistant-Service-Key
in: header
required: false
schema:
title: X-Assistant-Service-Key
type: string
nullable: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyCreate'
responses:
'200':
description: Already exists (idempotent). Successful Response
content:
application/json:
schema:
$ref: >-
#/components/schemas/StandardResponse_ApiKeyCreateResultPublic_
'201':
description: Successful Response
content:
application/json:
schema:
$ref: >-
#/components/schemas/StandardResponse_ApiKeyCreateResultPublic_
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/WrappedValidationError'
components:
schemas:
ApiKeyCreate:
properties:
principal_id:
title: Principal Id
description: >-
The ID of the principal to create the API key for. Required when
using service credential authentication; ignored when using
principal API key authentication.
type: string
format: uuid
nullable: true
name:
type: string
maxLength: 255
title: Name
description: The display name for this API key. Max 255 characters.
scopes:
items:
type: string
type: array
title: Scopes
description: >-
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:
title: Expires At
description: >-
The expiry timestamp for this key, in ISO 8601 format. If omitted,
the key does not expire.
type: string
format: date-time
nullable: true
type: object
required:
- name
title: ApiKeyCreate
description: Request payload for creating an API key.
StandardResponse_ApiKeyCreateResultPublic_:
properties:
success:
type: boolean
title: Success
default: true
result:
$ref: '#/components/schemas/ApiKeyCreateResultPublic'
suggestion:
type: string
title: Suggestion
default: ''
message:
type: string
title: Message
default: ''
meta:
$ref: '#/components/schemas/PaginationMeta'
nullable: true
type: object
required:
- result
title: StandardResponse[ApiKeyCreateResultPublic]
WrappedValidationError:
title: WrappedValidationError
type: object
required:
- success
- error
properties:
success:
type: boolean
const: false
default: false
title: Success
error:
type: object
title: Error
required:
- detail
properties:
detail:
type: array
title: Detail
items:
$ref: '#/components/schemas/ValidationError'
ApiKeyCreateResultPublic:
properties:
api_key:
$ref: '#/components/schemas/ApiKeyPublicRead'
raw_key:
type: string
title: Raw Key
description: >-
The plaintext API key. Returned only once at creation time — store
it securely as it cannot be retrieved again.
type: object
required:
- api_key
- raw_key
title: ApiKeyCreateResultPublic
description: Create API key result payload without delegation internals.
PaginationMeta:
properties:
total:
title: Total
type: integer
nullable: true
offset:
title: Offset
type: integer
nullable: true
limit:
title: Limit
type: integer
nullable: true
has_more:
title: Has More
type: boolean
nullable: true
after:
title: After
type: string
nullable: true
before:
title: Before
type: string
nullable: true
type: object
title: PaginationMeta
description: |-
Pagination metadata for list responses.
Supports both legacy offset-based and cursor-based pagination.
Cursor fields (``has_more``, ``after``, ``before``) are populated for
cursor-paginated endpoints. Legacy fields (``offset``, ``limit``) are
populated when the caller uses the deprecated ``offset`` parameter.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
ApiKeyPublicRead:
properties:
id:
type: string
format: uuid
title: Id
description: The API key ID.
principal_id:
type: string
format: uuid
title: Principal Id
description: The ID of the principal this key belongs to.
pact_id:
title: Pact Id
description: >-
Optional pact binding for this key. When set, requests made with
this key are executed within the context of the specified pact.
type: string
format: uuid
nullable: true
name:
type: string
title: Name
description: The display name of this API key.
key_prefix:
type: string
title: Key Prefix
description: >-
The first few characters of the API key, for identification
purposes.
scopes:
items:
type: string
type: array
title: Scopes
description: The access scopes granted to this key.
expires_at:
title: Expires At
description: >-
The expiry timestamp for this key, in ISO 8601 format. Null if no
expiry.
type: string
format: date-time
nullable: true
last_used_at:
title: Last Used At
description: >-
The timestamp when this key was last used, in ISO 8601 format. Null
if never used.
type: string
format: date-time
nullable: true
is_revoked:
type: boolean
title: Is Revoked
description: 'Whether this key has been revoked. `true`: revoked. `false`: active.'
revoked_at:
title: Revoked At
description: >-
The timestamp when this key was revoked, in ISO 8601 format. Null if
not revoked.
type: string
format: date-time
nullable: true
created_at:
type: string
format: date-time
title: Created At
description: The timestamp when the key was created, in ISO 8601 format.
updated_at:
type: string
format: date-time
title: Updated At
description: The timestamp when the key was last updated, in ISO 8601 format.
type: object
required:
- id
- principal_id
- name
- key_prefix
- scopes
- expires_at
- last_used_at
- is_revoked
- revoked_at
- created_at
- updated_at
title: ApiKeyPublicRead
description: Public API key response payload without delegation internals.
````