keystone — REST API

REST API — keystone — branch stable/2026.2

Branch stable/2026.2 @ e6dc5ae079e6 — repository https://opendev.org/openstack/keystone — analysed on 2026-10-28

The route table below was not read from the api-ref: it was extracted from the running Flask application (app.url_map of keystone.server.flask.application.application_factory). That gives 259 method + path pairs on 125 paths. The handler of each one is the real method (decorators unwrapped), and its policy rule comes from the operations declared by each default policy rule (keystone/common/policies/). HEAD is accepted wherever GET is, and is not listed.

1. Conventions shared by every endpoint

Request processing

• Pipeline (keystone/server/flask/core.py:39-70, applied by keystone/server/flask/core.py:93-142), in request order:
  1. ProxyFix (werkzeug);
  2. oslo CORS;
  3. RequestBodySizeLimiter;
  4. HTTPProxyToWSGI;
  5. osprofiler;
  6. RequestId;
  7. URLNormalizingMiddleware, which removes a trailing / (keystone/server/flask/request_processing/middleware/url_normalize.py:16);
  8. AuthContextMiddleware, which validates X-Auth-Token and builds the request context (keystone/server/flask/request_processing/middleware/auth_context.py). Then the Flask application runs before_request request logging and JSON body checks (keystone/server/flask/application.py:211-212).
• **/healthcheck** is served by oslo.middleware's healthcheck application, mounted next to Flask (keystone/server/flask/application.py:228-237).
• Body: on POST, PUT and PATCH, a body that is not JSON is rejected with 400 (keystone/server/flask/request_processing/json_body.py:23). Exceptions are application/x-www-form-urlencoded on /v3/OS-OAUTH2/token, and the federation protocol endpoints, which receive SAML/OIDC posts.
• Every response carries Vary: X-Auth-Token (keystone/server/flask/application.py:106-110). A 204 has no Content-Type (keystone/server/flask/common.py:182).
• No microversions: Keystone exposes a single v3 version. Discovery is GET / (300 Multiple Choices, the version list) and GET /v3 (version document). Both answer in JSON Home when the client sends Accept: application/json-home (keystone/api/discovery.py:44-65).

Authorisation

• Every handler must call ENFORCER.enforce_call(action=...) or be marked @unenforced_api. Otherwise the request fails: _assert_rbac_enforcement_called (keystone/server/flask/common.py:160) turns a missing check into a 500.
• enforce_call first requires an authenticated context (401 otherwise, keystone/common/rbac_enforcer/enforcer.py:300-320). It then evaluates the oslo.policy rule with the token's roles and scope; a refusal is 403 ForbiddenAction (keystone/common/rbac_enforcer/enforcer.py:102-136).
• The default rules combine three ingredients (keystone/common/policies/base.py:47-76):
  • the token's scope: system (system_scope:all), domain or project;
  • the default roles reader ⊂ member ⊂ admin, as implied roles created by keystone-manage bootstrap;
  • ownership, for example user_id:%(target.credential.user_id)s.

Lists

• Filters are query parameters named after an attribute, with optional comparators __contains, __icontains, __startswith, __istartswith, __endswith, __iendswith, and __eq/__neq… where supported (keystone/server/flask/common.py:903-972).
• Pagination: limit and marker are bounded by [DEFAULT]/max_db_limit and by the per-driver list_limit. When the list is cut, the response says so: "truncated": true and a links.next URL with the next marker (keystone/server/flask/common.py:701-764).
• Links: every entity has links.self. Every collection has links.self, links.next and links.previous.

Quirk: methods declared on a shared resource

Some resources serve the collection and the member with the same class, for example /v3/policies and /v3/OS-FEDERATION/mappings. Flask therefore lists the member methods on the collection path too, for example DELETE /v3/policies. Calling them there without an ID raises a TypeError, which the global handler turns into a **400 ValidationError** (keystone/server/flask/application.py:176-183), not a 405. A rewrite should answer 405, but must know that clients currently see 400.

2. Functional description by area

2.1 Authentication and tokens (/v3/auth/*)

**POST /v3/auth/tokens: issue a token.**

• Purpose: authenticate a user with one or more methods and obtain a token, unscoped or scoped to a project, a domain, the system, or a trust.
• Actor: anyone; the endpoint is not authenticated (@unenforced_api).
• Flow (keystone/api/auth.py:320-336, keystone/api/_shared/authentication.py:208-282):
  1. The auth body is validated by validate_issue_token_auth.
  2. If the WSGI server set REMOTE_USER, the external method runs first.
  3. Each method listed in identity.methods runs its plugin, chosen from [auth]/methods (default external, password, token, oauth1, mapped, application_credential, ec2credential, keystone/conf/constants.py:19-27). A plugin may answer "more steps needed": the response is then 401 with an auth receipt (MFA, see below).
  4. Without an explicit scope, the user's default_project_id is used, if the project and its domain are enabled and the user has a role on it. Otherwise the token is unscoped (keystone/api/_shared/authentication.py:34-117).
  5. The user's MFA rules are checked. Missing methods give 401 InsufficientAuthMethods, with an Openstack-Auth-Receipt header.
  6. The token is issued (keystone/token/provider.py:276-390). Its expiry is [token]/expiration (default 3600 s), capped by the expiry of the trust or application credential in use.
  7. A trust with remaining_uses has one use consumed after issuance.
• Response: 201 with the token ID in the X-Subject-Token header. The body holds token (user, methods, roles, scope, expires_at, issued_at, audit_ids, and catalog unless ?nocatalog).
• Password method (keystone/auth/plugins/password.py:24-44, keystone/identity/backends/sql.py:63-123). Checks run in this order:
  1. locked account → 401 AccountLocked;
  2. wrong password → failure counter +1 and 401 "Invalid username or password";
  3. disabled user → 401 UserDisabled;
  4. expired password → 401 PasswordExpired. The lockout is driven by [security_compliance]/lockout_failure_attempts and lockout_duration. A successful authentication resets the counter and updates last_active_at.
• Auth receipts (MFA): when a user has MFA rules and only part of them is satisfied, the 401 carries a receipt. The client sends it back in Openstack-Auth-Receipt with the missing methods (keystone/receipt/handlers.py, keystone/server/flask/application.py:128-129).

**GET/HEAD /v3/auth/tokens: validate a token** (keystone/api/auth.py:279-317).

• The token to check is in X-Subject-Token; the caller authenticates with its own X-Auth-Token. Policy: identity:validate_token (GET) or identity:check_token (HEAD).
• ?allow_expired=1 accepts a token expired for less than [token]/allow_expired_window (default 2 days). ?nocatalog drops the catalog.
• A token is valid when all these hold (keystone/token/provider.py:139-275):
  • it decrypts with one of the Fernet keys (or verifies with a JWS key);
  • it has not expired;
  • it matches no revocation event;
  • its user is still enabled;
  • if it comes from an application credential with access rules, the caller sends OpenStack-Identity-Access-Rules ≥ 1.0.
• Every failure becomes **404 TokenNotFound**, never a 401: a stale token looks like a token that does not exist.
• Side effect: validating a token whose user was disabled writes a revocation event for that user and empties the token cache (keystone/token/provider.py:218-229).

**DELETE /v3/auth/tokens: revoke a token** (keystone/api/auth.py:338-357, keystone/token/provider.py:406-434).

• Writes a revocation event on the token's audit_id.
• By default (?cascade=true), it also writes one on its chain (audit_chain_id), so the scoped tokens obtained from it are revoked too, and the whole token cache is emptied. ?cascade=false limits the revocation to that token.

**Other /v3/auth endpoints**: GET /v3/auth/catalog, /v3/auth/projects, /v3/auth/domains and /v3/auth/system list, for the caller's token, its catalog and the projects, domains or system scope it could rescope to (keystone/api/auth.py:119-260). GET /v3/auth/tokens/OS-PKI/revoked is a fossil: it answers 410 if [token]/revoke_by_id = false, 403 otherwise (keystone/api/auth.py:262-276).

2.2 Users, groups, passwords

• Users (keystone/api/users.py, keystone/identity/core.py): CRUD within a domain.
  • The identity driver is chosen per domain: SQL, or LDAP when [identity]/domain_specific_drivers_enabled points a domain to an LDAP configuration.
  • Users from LDAP or federation get a public ID computed in the id_mapping table (sha256 generator).
  • default_project_id cannot be a domain (keystone/identity/core.py:1076-1093).
  • Disabling or deleting a user triggers, through internal callbacks: revocation of the user's tokens, deletion of their application credentials and of the trusts where they are trustee, and invalidation of the caches (see async processing).
• Passwords (POST /v3/users/{user_id}/password) is the self-service change. It is unauthenticated: the body carries the original password, which is checked. The rules come from [security_compliance]:
  • password_regex;
  • unique_last_password_count (password history);
  • minimum_password_age;
  • password_expires_days;
  • change_password_upon_first_use. Breaking one of them gives 400 PasswordValidationError and its variants (see errors).
• Groups: CRUD and membership (/v3/groups/{group_id}/users/{user_id}). A user and a group from different backends cannot be linked (403 CrossBackendNotAllowed).
• **DELETE /v3/users/{user_id}/tokens** revokes all of a user's tokens (policy identity:revoke_tokens_for_user, keystone/api/users.py:949).

2.3 Projects, domains, tags, domain configuration

• Projects form a tree (parent_id). A domain is a root project with is_domain = true. The rules (keystone/resource/core.py:62-620):
  • Hierarchy:
    • maximum depth [DEFAULT]/max_project_tree_depth, or less if the limit model requires it (403);
    • a project's domain must be the domain of its parent (400);
    • no creation under a disabled project (400);
    • parent_id and is_domain cannot be changed (403 and 400).
  • Names: a name is unique within a domain (409). With [resource]/project_name_url_safe set, a name with reserved URL characters is refused (400).
  • Disabling: a project with enabled children cannot be disabled (403), unless ?cascade. In that case only enabled can change (400 otherwise).
  • Deleting: only a leaf can be deleted, unless ?cascade, which requires the whole subtree to be disabled (403). Deleting a project removes its assignments, credentials, trusts and limits (keystone/resource/core.py:521-539).
  • Immutable resources: a project, domain or role with the immutable option refuses updates and deletion (403 ResourceUpdateForbidden / ResourceDeleteForbidden).
• Domains: an enabled domain cannot be deleted. Deleting a domain removes its projects, users, groups, assignments and federated identity providers (internal callbacks).
• Tags: /v3/projects/{id}/tags[/{tag}], and filters tags, tags-any, not-tags, not-tags-any on GET /v3/projects.
• Domain configuration (/v3/domains/{id}/config[...]): per-domain identity settings (an LDAP driver per domain). Only whitelisted options are allowed; sensitive ones (passwords) are stored apart and never returned (keystone/resource/core.py:1226-1600).

2.4 Roles, implied roles, assignments

• Roles are global, or domain-specific (domain_id). A domain-specific role can only be assigned in its domain (403 DomainSpecificRoleMismatch).
• Implied roles (/v3/roles/{prior}/implies/{implied}): a role brings others when the token is computed. The default chain is admin → member → reader. Some roles cannot be implied: [assignment]/prohibited_implied_role, admin by default (403 InvalidImpliedRole).
• Assignments (grants): user or group × role × project, domain or system. OS-INHERIT assignments are inherited by every project under a domain or project.
• **GET /v3/role_assignments** lists them, with ?effective (groups expanded, inheritance and implied roles applied), ?include_names and ?include_subtree. Effective assignments are cached in the computed assignments region, invalidated on every change.

2.5 Catalog, endpoint filtering, endpoint policies

• Regions (tree, cycles refused with 400 CircularRegionHierarchyError), services and endpoints (interface = public/internal/admin, URL validated). These build the catalog returned in tokens.
• OS-EP-FILTER: associates endpoints or endpoint groups with projects, to restrict the catalog of a project-scoped token. It needs [catalog]/driver = sql and [endpoint_filter].
• OS-ENDPOINT-POLICY and /v3/policies: store opaque blobs (old policy files) and associate them with endpoints, services or regions. These APIs are deprecated since Queens (keystone/api/policy.py:76-96).

2.6 Credentials, EC2 and S3

• **/v3/credentials: blobs belonging to a user, **encrypted with the credential Fernet keys ([credential]/key_repository). The ID of an EC2 credential is sha256(access). The number per user is capped by [credential]/user_limit (403).
• Security fix on this branch (see 06): the trust_id, app_cred_id and access_token_id fields of an EC2 blob are now server-managed (keystone/api/credentials.py:144-170). Any client-supplied value is stripped, and only the context of the token used is written.
• **POST /v3/ec2tokens** and **POST /v3/s3tokens** exchange an AWS-style signature for a Keystone token (keystone/api/_shared/EC2_S3_Resource.py). They check:
  • the signature (_check_signature);
  • the timestamp: a signed request older than [credential]/auth_ttl is refused (keystone/api/_shared/EC2_S3_Resource.py:46-68);
  • since this branch, that the credential's owner is a party to the referenced trust, or owns the application credential or the OAuth1 access token (keystone/api/_shared/EC2_S3_Resource.py:166-220). GET on these two paths answers 405.

2.7 Application credentials and access rules

• A user creates a credential for one project with a subset of their roles (keystone/application_credential/core.py:87-150), with optional expires_at, unrestricted and access_rules (service, path, method).
  • The secret is generated if not given, returned once only, and stored hashed.
  • Requesting a role the user does not have gives 404 RoleAssignmentNotFound.
  • The number per user is capped ([application_credential]/user_limit, 403).
• Effects elsewhere: a token obtained with an application credential:
  • expires no later than the credential;
  • carries only the credential's roles;
  • cannot create other credentials or trusts, unless unrestricted. Disabling or deleting the user, or removing their role on the project, deletes their application credentials (callbacks).

2.8 Trusts (OS-TRUST)

• A trustor delegates roles on a project to a trustee, possibly with impersonation, an expiry, remaining_uses and re-delegation (keystone/trust/core.py:57-205).
• Re-delegation rules (403):
  • depth within [trust]/max_redelegation_count;
  • no remaining_uses on a re-delegated trust;
  • expiry within the parent's;
  • roles a subset of the parent's;
  • no impersonation if the parent has none.
• remaining_uses must be positive (400).
• Deleting the trustee deletes their trusts. An exhausted trust gives 403 TrustUseLimitReached.

2.9 Federation (OS-FEDERATION)

• Configuration:
  • identity providers (remote_ids; maximum length 255 since this branch, see 06);
  • protocols (saml2, openid, mapped…);
  • mappings: JSON rules that turn the assertion's attributes into a user, groups and projects (keystone/federation/utils.py:469-1130);
  • service providers (Keystone-to-Keystone).
• Authentication: GET/POST /v3/OS-FEDERATION/identity_providers/{idp}/protocols/{protocol}/auth (and the WebSSO variants).
  • The web server (mod_shib, mod_auth_openidc) has already validated the assertion. Keystone reads the attributes from the WSGI environment and applies the mapping.
  • It creates or updates a shadow user (federated_user, nonlocal_user) and expiring group memberships (expiring_user_group_membership, TTL authorization_ttl).
  • It returns an unscoped federated token (keystone/auth/plugins/mapped.py:41-500).
• Keystone as IdP: POST /v3/auth/OS-FEDERATION/saml2[/ecp] produces a SAML assertion **signed by the xmlsec1 binary** (keystone/federation/idp.py:447-541). GET /v3/OS-FEDERATION/saml2/metadata publishes the metadata.

2.10 OAuth 1.0a and OAuth 2.0

• OAuth1 (deprecated): consumers, request token, authorisation by a user, access token, then an oauth1 token.
• OAuth2 (POST /v3/OS-OAUTH2/token, keystone/api/os_oauth2.py:74-130):
  • grant client_credentials only (400 otherwise);
  • the client authenticates either with an application credential (client_secret_basic) or with a client certificate (tls_client_auth, mTLS);
  • in the mTLS case, the token carries the certificate thumbprint, which keystonemiddleware checks.
  • Errors follow RFC 6749 ({"error": "invalid_client", ...}, keystone/oauth2/handlers.py). The other methods answer 405.

2.11 Unified limits

• Registered limits are a default per service, region and resource name. Limits override them per project or domain.
• The model ([unified_limit]/enforcement_model: flat or strict_two_level, GET /v3/limits/model) checks consistency: in strict_two_level, children cannot exceed their parent, and the tree is limited to 2 levels (403 InvalidLimit).
• A registered limit that is referenced cannot be modified (403 RegisteredLimitError).

2.12 Revocation events and certificates

• GET /v3/OS-REVOKE/events[?since=] lists the revocation events (policy identity:list_revoke_events).
• OS-SIMPLE-CERT is deprecated: it answers 410 (keystone/api/os_simple_cert.py).

3. Route table (extracted from the application)

Handler: the method that serves the call. Policy rule: the default rule that enforce_call evaluates (rules and check strings in _rewrite/policies_stable-2026.2.json). "none (unauthenticated)": an @unenforced_api handler. "—": no documented rule; the handler either checks nothing beyond authentication, or answers 405 or 410.

Discovery (3 operations)

Authentication and tokens (8 operations)

Federation (36 operations)

Users, groups and passwords (19 operations)

Application credentials and access rules (7 operations)

Credentials, EC2 and S3 (13 operations)

Projects and domains (29 operations)

Roles, implied roles and assignments (53 operations)

Catalog: regions, services, endpoints (16 operations)

Endpoint filtering and endpoint policies (35 operations)

Trusts (4 operations)

OAuth 1.0a and OAuth 2.0 (22 operations)

Unified limits (11 operations)

Revocation events and certificates (3 operations)

Source: reverse-spec-keystone/01-rest-api_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.