Skip to main content
The Ory Kratos Admin API provides administrative endpoints for managing identities, sessions, recovery flows, and courier messages. This API is designed for backend services and administrators to perform privileged operations that are not available through the public API.

​
Authentication

All Admin API endpoints require authentication using an Ory Access Token. Include the token in the Authorization header: 
Authorization: Bearer ory_at_...
For self-hosted deployments, you can configure the admin API endpoint separately from the public API endpoint.

​
Base URL

The Admin API is available at:
  • Ory Network: https://{project-slug}.projects.oryapis.com/admin
  • Self-hosted: Configured via serve.admin.base_url in your Kratos configuration

​
Available endpoints

The Admin API is organized into the following categories:

​
Identities

Manage user identities, credentials, and authentication methods:
  • Create, read, update, and delete identities
  • Import credentials (passwords, social sign-in, MFA)
  • Manage identity sessions
  • Look up identities by credentials or external ID
View identity endpoints →

​
Sessions

Manage authentication sessions:
  • List all sessions
  • Get session details
  • Deactivate sessions
  • Extend session lifetime
View session endpoints →

​
Recovery

Generate recovery codes and links for account recovery:
  • Create recovery codes
  • Create recovery links
View recovery endpoints →

​
Courier

Manage email and SMS messages sent by Kratos:
  • List courier messages
  • Get message details and delivery status
View courier endpoints →

​
Rate limiting

Admin API endpoints have different rate limit buckets based on their resource intensity:
  • kratos-admin-low: Read operations with minimal overhead
  • kratos-admin-medium: Standard list and read operations
  • kratos-admin-high: Write operations and resource-intensive queries

​
Error handling

The Admin API uses standard HTTP status codes and returns errors in a consistent JSON format: 
{
  "error": {
    "code": 404,
    "status": "Not Found",
    "message": "The requested resource could not be found",
    "reason": "Identity with ID abc123 does not exist"
  }
}

​
Common error codes

​
400
Bad Request
The request payload is invalid or improperly formatted.
​
401
Unauthorized
Authentication credentials are missing or invalid.
​
404
Not Found
The requested resource does not exist.
​
409
Conflict
The request conflicts with existing data (e.g., duplicate identity).
​
500
Internal Server Error
An unexpected error occurred on the server.

​
Pagination

List endpoints support token-based pagination:
  • page_size: Number of items per page (default: 250, max: 1000)
  • page_token: Token for the next page of results
The response includes a Link header with next/previous page URLs when applicable.

​
Best practices

​
Use appropriate consistency levels

For list operations, you can specify a consistency level:
  • strong: Guaranteed most recent data (slower)
  • eventual: Data may be ~5 seconds old (faster)

​
Import credentials securely

When importing identities with credentials:
  • Pre-hash passwords using BCrypt for better performance
  • Limit batch size to 1,000 identities with hashed passwords
  • Limit batch size to 200 identities with plaintext passwords

​
Handle rate limits

Implement exponential backoff when you receive 429 (Too Many Requests) responses.

​
Validate identity schemas

Ensure identity traits conform to your configured JSON schema before creating or updating identities.

Build docs developers (and LLMs) love

Get started for freeTalk to us