canonical: https://jentic.com/apis/ory.sh/ory

# Ory Sh Ory APIs

Ory APIs provide a unified surface over Ory Network's identity, session, OAuth 2.0, OpenID Connect, and permission services. Developers can register and authenticate users, run self-service flows for login, registration, recovery, verification, and settings, issue and introspect OAuth 2.0 tokens, and evaluate fine-grained permissions backed by Google Zanzibar. With 146 endpoints across identity, frontend, courier, oAuth2, OIDC, permission, and project management, Ory replaces a stack of bespoke auth code for SaaS and B2B platforms.

## For AI agents

Run identity, OAuth 2.0, OpenID Connect, and Zanzibar-style permission checks against Ory Network. Agents can manage users, sessions, OAuth clients, and access policies through a single API.

## Scope

Does not handle payment processing, CRM, or general user analytics - use for identity, OAuth 2.0, OpenID Connect, and Zanzibar permissions only.

## Capabilities

- Run self-service login, registration, recovery, and settings flows for end users
- Manage OAuth 2.0 clients, authorisation requests, and token introspection
- Issue and revoke user sessions, including impersonation and refresh handling
- Define identity schemas and create or look up identities by trait
- Evaluate Zanzibar-style permission checks against Ory Keto relations
- Send transactional courier messages tied to identity flows such as recovery and verification
- Provision and configure Ory Network projects, namespaces, and workspaces

## Use cases

### Customer Identity for SaaS Applications

SaaS teams use Ory to ship login, registration, MFA, and account recovery without building auth from scratch. The frontend self-service flows handle browser and native clients, while the identity admin endpoints let backend services list, update, and deactivate users. A typical embedded login page goes live in 1-2 days using the prebuilt Ory Account Experience or in a week with a fully custom UI.

Example prompt: Initialise a registration flow with GET `/self-service/registration/api`, then submit the user's email and password to the returned action URL and capture the resulting session token.

### OAuth 2.0 Authorisation Server

Platforms that expose third-party APIs use Ory Hydra (surfaced via `/admin/clients` and /oauth2/*) as their OAuth 2.0 and OpenID Connect provider. Endpoints cover the full authorisation code, client credentials, and refresh token flows, plus token introspection and revocation. Hydra handles consent UI hand-off, so teams keep their own login experience while delegating protocol compliance.

Example prompt: Create a new confidential OAuth client by POSTing to `/admin/clients` with client_name, redirect_uris, and grant_types ['authorization_code','refresh_token'].

### Fine-Grained Authorisation with Keto

Applications that need per-resource permission checks (who can read which document, who can edit which project) use Ory's permission API to evaluate Zanzibar-style relation tuples. Endpoints under /relation-tuples and /permissions answer 'subject X has permission Y on resource Z' in milliseconds, letting agents enforce ACLs without hard-coding role checks in application code.

Example prompt: Check whether user 'alice@example.com' has 'editor' permission on document 'doc-42' by calling GET `/relation-tuples/check` with subject and object query params.

### AI Agent Identity Plumbing via Jentic

Agents that act on behalf of human users need session validation, OAuth token issuance, and permission checks at runtime. Through Jentic, an agent searches for 'check user permission' and Ory's permission endpoints surface with their schemas. The agent can then enforce per-call authorisation without the developer wiring a bespoke Ory client into the agent loop.

Example prompt: Use Jentic to search 'verify a session token', load the GET `/sessions/whoami` schema, and execute it with the session cookie supplied by the calling user.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/sessions/whoami` | Return the current user's session |
| GET | `/admin/identities` | List identities in the project |
| POST | `/admin/identities` | Create a new identity |
| POST | `/admin/clients` | Register an OAuth 2.0 client |
| POST | `/oauth2/token` | Issue an OAuth 2.0 token |
| POST | `/oauth2/introspect` | Introspect an OAuth 2.0 access or refresh token |
| GET | `/relation-tuples/check` | Check a permission relation tuple |
| GET | `/.well-known/openid-configuration` | OpenID Connect discovery document |

## Key resources

- **Identity** — Admin operations to create, list, update, and delete identities, including identity schemas
- **Frontend** — Self-service flows for login, registration, recovery, verification, settings, and logout
- **OAuth2 and OIDC** — OAuth 2.0 client management, token issuance, introspection, revocation, and OpenID Connect discovery
- **Permission** — Zanzibar-style relation tuples and permission checks for fine-grained authorisation
- **Project** — Ory Network project configuration, namespaces, and workspace management
- **Courier** — Transactional message dispatch tied to identity flows

## Why Jentic

- **Setup:** Wiring the Ory APIs by hand means choosing among OAuth2, bearer, and basic auth across identity, OAuth 2.0, and permission surfaces, resolving your {project_slug}.projects.oryapis.com host, and mapping the routes yourself. Through Jentic you install once, import Ory from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** You choose which Ory operations the agent may call, so you can limit it to the operations it needs, such as checking a session with whoami or a relation-tuple permission, while admin operations like creating identities or OAuth clients stay out of the allowed set unless you add them.
- **Credential handling:** Your Ory access tokens, OAuth client secrets, and workspace API keys are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check a user permission' or 'introspect an OAuth token', and Jentic returns the matching Ory operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Auth0 Management API** — Auth0 provides a fully managed identity-as-a-service offering; Ory is open source first with a managed cloud option.
- **Okta API** — Okta is an enterprise IDaaS with deep workforce identity features; Ory targets developer-led identity for product use cases.
- **Keycloak API** — Keycloak is an open-source identity provider with realms and server-side admin; Ory is split into modular services with a Network-hosted offering.
- **Clerk Backend API** — Clerk handles user-facing UI components alongside identity APIs; pairs with Ory when teams want Clerk's UI but Ory's permissions backend.

## FAQ

### What authentication does the Ory API use?

Ory APIs accept multiple schemes depending on the operation: OAuth 2.0 access tokens for protected user data, an Ory access token (Bearer) for project-admin actions, an Ory workspace API key for cross-project operations, and HTTP Basic for legacy OAuth client endpoints. Through Jentic the appropriate credential for each operation is held in your Jentic One instance and injected at call time.

### Can I issue OAuth 2.0 tokens with the Ory API?

Yes. POST `/oauth2/token` implements the standard OAuth 2.0 token endpoint and supports authorization_code, client_credentials, and refresh_token grants. Companion endpoints `/oauth2/introspect` and `/oauth2/revoke` handle introspection and revocation.

### What are the rate limits for the Ory API?

Ory Network applies plan-based rate limits per project, but specific limits are not encoded in the OpenAPI spec. The API returns a 429 with a Retry-After header when a project exceeds its quota. Self-hosted deployments of Ory Kratos, Hydra, and Keto have no built-in rate limits.

### How do I check a user's permission through Jentic?

Through Jentic, search for 'check user permission', load the GET `/relation-tuples/check` schema, and execute it with namespace, object, relation, and subject_id query parameters. Jentic injects the project's Ory access token automatically.

### How do I run a self-service login flow with the Ory API?

Initialise the flow with GET `/self-service/login/api` or `/self-service/login/browser`, follow the action URL returned in the flow body, and submit the user's credentials. On success the response contains a session token (API flow) or sets a session cookie (browser flow).

### Is the Ory API free to use?

Ory Network has a free Developer plan with limited monthly active users; production tiers are usage-priced based on MAUs and add-ons. The underlying Ory Kratos, Hydra, and Keto projects are open source and free to self-host.

### Can I limit what my agent is allowed to do with the Ory API?

Yes. Because you run your own self-hosted Jentic One instance, your rules decide which Ory operations and credentials the agent may use. You can allow it only the operations it needs, such as GET `/sessions/whoami` to verify a session or GET `/relation-tuples/check` to evaluate a permission, while admin operations like POST `/admin/identities` or POST `/admin/clients` stay out of the allowed set unless you add them. This keeps the agent scoped to read-level identity and permission checks rather than creating identities or OAuth clients.