OAuth Resource Server HTTP API

Enterprise

Appropriate Vault Enterprise license required

The /sys/oauth-resource-server endpoints provide OAuth Resource Server configuration management and Rich Authorization Request (RAR) type discovery capabilities. These endpoints support:

OAuth resource server configuration profile management.
Authorization details type catalog discovery (RFC 9396).
OAuth protected resource metadata publication (RFC 9728).
JSON schema retrieval for authorization_details validation.

Configuration profile management

Manage OAuth resource server configuration profiles under /sys/config/oauth-resource-server, including creating, reading, updating, and deleting profiles. For the full list of endpoints, parameters, and examples, refer to the /sys/config/oauth-resource-server API reference.

Authorization details type discovery

The following endpoints support OAuth 2.0 Rich Authorization Request (RAR) type discovery per RFC 9396 and RFC 9728.

Unrestricted endpoint

Clients can call the API path without authenticating to Vault.

List authorization details types

Fetch all supported authorization_details type identifiers.

Method	Path
`LIST`	`/sys/oauth-resource-server/authorization-details-types`

Sample request

$ curl \
    --request LIST \
    ${VAULT_ADDR}/v1/sys/oauth-resource-server/authorization-details-types

Sample response

{
  "data": {
    "keys": ["vault:path_access"]
  }
}

Read authorization details type catalog

Fetch the catalog metadata for all supported authorization_details types.

Method	Path
`GET`	`/sys/oauth-resource-server/authorization-details-types`

Sample request

$ curl \
    ${VAULT_ADDR}/v1/sys/oauth-resource-server/authorization-details-types

Sample response

{
  "data": {
    "api_version": "v1",
    "default_unknown_type_behavior": "deny",
    "types": [
      {
        "type": "vault:path_access",
        "status": "generally-available",
        "schema_version": "1.0.0",
        "title": "Vault Path Access",
        "description": "Constrains a token to specific Vault path/capability combinations.",
        "docs_url": "https://developer.hashicorp.com/vault/docs",
        "introduced_in": "2.0.0-ent",
        "schema_path": "/v1/sys/oauth-resource-server/authorization-details-types/vault:path_access/schema"
      }
    ]
  }
}

Response fields

api_version (string) - API version for the type catalog contract (currently "v1").
default_unknown_type_behavior (string) - Default behavior for unknown authorization_details types (currently "deny").
types (array) - Array of type summary objects:
- type (string) - Type identifier (for example, "vault:path_access").
- status (string) - Lifecycle status. Must be one of:
- schema_version (string) - Semantic version of the type schema (MAJOR.MINOR.PATCH).
- title (string) - Human-readable type title.
- description (string) - Human-friendly summary of how Vault uses the access type.
- docs_url (string) - URL to Vault's documentation for this type. Vault populates this field from its built-in type registry; it is not user-configurable.
- introduced_in (string) - Vault version that introduced the type.
- deprecated_in (string) - Vault version that deprecated the type. Vault omits the deprecated_in for non-deprecated types.
- schema_path (string) - API path to retrieve the JSON Schema.

Read authorization details type

Fetch the detailed metadata for a specific authorization_details type.

Method	Path
`GET`	`/sys/oauth-resource-server/authorization-details-types/:type`

Parameters

type (string: <required>) - The authorization_details type identifier (for example, "vault:path_access"). Specified in the URL.

Sample request

$ curl \
    ${VAULT_ADDR}/v1/sys/oauth-resource-server/authorization-details-types/vault:path_access

Sample Response

{
  "data": {
    "type": "vault:path_access",
    "status": "generally-available",
    "schema_version": "1.0.0",
    "title": "Vault Path Access",
    "description": "Constrains a token to specific Vault path/capability combinations.",
    "docs_url": "https://developer.hashicorp.com/vault/docs",
    "introduced_in": "2.0.0-ent",
    "required_fields": ["type", "path", "capabilities"],
    "optional_fields": [],
    "matching_semantics": {
      "path_match": "evaluated_using_vault_acl_path_matching_semantics",
      "capability_match": "evaluated_using_vault_acl_operation_authorization_semantics"
    },
    "examples": [
      {
        "type": "vault:path_access",
        "path": "kv/data/team-a/secret",
        "capabilities": ["read"]
      }
    ],
    "schema_path": "/v1/sys/oauth-resource-server/authorization-details-types/vault:path_access/schema"
  }
}

Response Fields

type (string) - Type identifier.
status (string) - Lifecycle status.
schema_version (string) - Semantic version of the type schema.
title (string) - Human-readable type title.
description (string) - Detailed description.
docs_url (string) - URL to Vault's documentation for this type. Vault populates this field from its built-in type registry; it is not user-configurable.
introduced_in (string) - Vault version that introduced the type.
deprecated_in (string) - Vault version that deprecated the type. Vault omits deprecated_in for non-deprecated types.
required_fields (array) - List of required field names.
optional_fields (array) - List of optional field names.
matching_semantics (object) - Description of how Vault evaluates the type.
examples (array) - Example authorization_details payloads.
schema_path (string) - API path to retrieve the JSON Schema.

Read authorization details type schema

Fetch the machine-readable JSON Schema for a specific authorization_details type.

Method	Path
`GET`	`/sys/oauth-resource-server/authorization-details-types/:type/schema`

Parameters

type (string: <required>) - The authorization_details type identifier. Specified in the URL.

Sample Request

$ curl \
    ${VAULT_ADDR}/v1/sys/oauth-resource-server/authorization-details-types/vault:path_access/schema

Sample Response

{
  "data": {
    "type": "vault:path_access",
    "schema_version": "1.0.0",
    "json_schema_draft": "2020-12",
    "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "required": ["type", "path", "capabilities"],
      "properties": {
        "type": {
          "const": "vault:path_access"
        },
        "path": {
          "type": "string",
          "minLength": 1
        },
        "capabilities": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "read",
              "list",
              "create",
              "update",
              "delete",
              "patch",
              "sudo",
              "subscribe",
              "recover"
            ]
          }
        }
      },
      "additionalProperties": false
    }
  }
}

Response Fields

type (string) - Type identifier.
schema_version (string) - Semantic version of the schema.
json_schema_draft (string) - JSON Schema draft version (currently "2020-12").
schema (object) - Complete JSON Schema document for validation.

OAuth protected resource metadata

Read protected resource metadata

Fetch the OAuth protected resource metadata per RFC 9728 for automated discovery by authorization servers.

Method	Path
`GET`	`/sys/oauth-resource-server/protected-resource-metadata`
`GET`	`/.well-known/oauth-protected-resource`

Both paths return identical responses. The well-known endpoint follows RFC 9728 conventions for automated discovery.

Sample request

$ curl \
    ${VAULT_ADDR}/v1/sys/oauth-resource-server/protected-resource-metadata

Or using the well-known endpoint:

$ curl \
    ${VAULT_ADDR}/.well-known/oauth-protected-resource

Sample response

{
  "data": {
    "resource": "https://vault.example.com",
    "authorization_servers": [
      "https://auth.example.com",
      "https://auth2.example.com"
    ],
    "authorization_details_types_supported": ["vault:path_access"],
    "bearer_methods_supported": ["header"],
    "rar_types_metadata_endpoint": "/v1/sys/oauth-resource-server/authorization-details-types"
  }
}

Response fields

resource (string) - The redirect address used by Vault as the resource server identifier.
authorization_servers (array) - List of trusted authorization server issuer IDs from enabled OAuth profiles. Omitted when no profiles exist (per RFC 9728).
authorization_details_types_supported (array) - List of supported authorization_details type identifiers.
bearer_methods_supported (array) - Token presentation methods (currently only "header").
rar_types_metadata_endpoint (string) - API path to the authorization_details type catalog.

Error responses

Type not found

Returned when reading a non-existent authorization_details type:

{
  "errors": ["type not found"]
}

For error responses related to configuration profile management (for example, profile not found or validation errors), refer to the /sys/config/oauth-resource-server API reference.

Authentication requirements

Authenticated endpoints

Configuration profile management endpoints under /sys/config/oauth-resource-server require a valid Vault token with appropriate permissions. For required capabilities, refer to the /sys/config/oauth-resource-server API reference.

Unauthenticated endpoints

The following endpoints are intentionally unauthenticated to support automated discovery:

The unauthenticated endpoints do not expose sensitive configuration data. Vault limits exposure to the type metadata and schema information.

OAuth Resource Server HTTP API

Configuration profile management

Authorization details type discovery

List authorization details types

Sample request

Sample response

Read authorization details type catalog

Sample request

Sample response

Response fields

Read authorization details type

Parameters

Sample request

Sample Response

Response Fields

Read authorization details type schema

Parameters

Sample Request

Sample Response

Response Fields

OAuth protected resource metadata

Read protected resource metadata

Sample request

Sample response

Response fields

Error responses

Type not found

Authentication requirements

Authenticated endpoints

Unauthenticated endpoints

Related documentation