> ## Documentation Index > Fetch the complete documentation index at: https://docs.ambient.market/llms.txt > Use this file to discover all available pages before exploring further. # Provision a principal, actor, and first public key > Atomically creates the minimum durable identity records required for public-key authentication. The authenticated actor must be explicitly listed in AMBIENT_OPERATOR_ACTORS. This is trusted provisioning, not a public registration endpoint. Creating distinct principal and actor IDs does not grant authority between them. ## OpenAPI ````yaml /openapi.yaml post /v1/admin/identities openapi: 3.1.0 info: title: Ambient HTTP API version: 0.1.0 description: > Create and operate deterministic markets through signed HTTP commands. Request bodies use strict JSON. Unknown fields and multiple JSON values are rejected. The maximum request body size is 1 MiB. Ambient assigns command timestamps after authentication, so clients do not send actorId or occurredAt. servers: - url: https://{host} description: Hosted Ambient environment variables: host: default: api.example.com description: API host supplied with your provisioned credentials. security: - AmbientActor: [] AmbientTimestamp: [] AmbientSignature: [] - AmbientBearer: [] tags: - name: Authentication description: >- Prove control of a registered actor key and obtain a short-lived bearer token. - name: Administration description: Trusted operator commands that are not public self-service APIs. - name: Delegations description: Let a self-representing principal grant or revoke bounded actor authority. - name: Markets description: Create, publish, and read markets. - name: Participation description: Submit claims and sealed bids to open markets. - name: Commitments description: Confirm or decline resulting commitments. - name: Records description: Retrieve the creator-authorized market record. - name: System description: Check service health. paths: /v1/admin/identities: post: tags: - Administration summary: Provision a principal, actor, and first public key description: | Atomically creates the minimum durable identity records required for public-key authentication. The authenticated actor must be explicitly listed in AMBIENT_OPERATOR_ACTORS. This is trusted provisioning, not a public registration endpoint. Creating distinct principal and actor IDs does not grant authority between them. operationId: provisionIdentity requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IdentityProvisioningRequest' responses: '201': description: Identity material provisioned or an identical command replayed. content: application/json: schema: $ref: '#/components/schemas/IdentityProvisioningResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' components: schemas: IdentityProvisioningRequest: type: object additionalProperties: false required: - commandId - principalId - actorId - keyId - publicKey properties: commandId: $ref: '#/components/schemas/CommandId' principalId: type: string minLength: 1 actorId: type: string minLength: 1 keyId: type: string minLength: 1 publicKey: type: string minLength: 43 maxLength: 43 description: Unpadded base64url encoding of a 32-byte Ed25519 public key. IdentityProvisioningResponse: type: object additionalProperties: false required: - principal - actor - key properties: principal: $ref: '#/components/schemas/Principal' actor: $ref: '#/components/schemas/Actor' key: $ref: '#/components/schemas/ActorKey' CommandId: type: string minLength: 1 description: >- Actor-scoped idempotency key. Retry the identical command with the same value. Principal: type: object additionalProperties: false required: - id - createdAt properties: id: type: string createdAt: type: string format: date-time disabledAt: type: string format: date-time Actor: type: object additionalProperties: false required: - id - createdAt properties: id: type: string createdAt: type: string format: date-time disabledAt: type: string format: date-time ActorKey: type: object additionalProperties: false required: - id - actorId - algorithm - publicKey - createdAt properties: id: type: string actorId: type: string algorithm: type: string const: Ed25519 publicKey: type: string description: Unpadded base64url encoding of the registered public key. createdAt: type: string format: date-time revokedAt: type: string format: date-time ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable detail. Clients should branch on code. ErrorCode: type: string enum: - invalid_request - unauthenticated - forbidden - identity_conflict - identity_not_found - delegation_not_found - delegation_conflict - delegation_inactive - not_found - method_not_allowed - idempotency_conflict - concurrent_update - internal_error - invalid_command - authority_reference_required - unknown_mechanism - invalid_mechanism_config - market_not_found - commitment_not_found - principal_not_authorized - version_conflict - invalid_market_transition - invalid_commitment_transition - actor_not_authorized - capacity_exhausted responses: BadRequest: description: The JSON or command fields are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: HMAC authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthenticated message: request authentication failed Forbidden: description: The actor or principal is not authorized for this action. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: >- The command conflicts with current state, version, capacity, or idempotency history. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: The command could not be completed because of an internal failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: AmbientActor: type: apiKey in: header name: X-Ambient-Actor description: Provisioned actor identifier. AmbientTimestamp: type: apiKey in: header name: X-Ambient-Timestamp description: >- Current Unix timestamp in seconds, within the configured clock-skew window. AmbientSignature: type: apiKey in: header name: Authorization description: | Ambient-HMAC followed by a space and the unpadded base64url HMAC-SHA256 signature. See Authentication and authority for the canonical input. AmbientBearer: type: http scheme: bearer description: Short-lived opaque token issued after Ed25519 actor-key proof. ````