/sys/config/oauth-resource-server

OAuth resource server configuration requires Vault Enterprise 2.1.0 or later.

The /sys/config/oauth-resource-server endpoint manages OAuth Resource Server configuration profiles. The profiles define how Vault validates externally issued JWTs (such as OAuth 2.0 access tokens) presented for authentication.

Each profile specifies an issuer, key material (JWKS or static PEM keys), audience restrictions, and other validation parameters. Vault uses these profiles to verify JWT signatures and claims before granting access.

JWT authentication through OAuth workflows requires the presenting entity to have an active registration in the Agent Registry. Vault rejects OAuth credentials for entities without an Agent Registry record.

By default, each OAuth Resource Server configuration profile requires OAuth 2.0 Rich Authorization Requests (RAR) in the JWTs it validates. Clients provide RAR in the authorization_details claim of the JWT. To allow JWTs that omit authorization_details, set optional_authorization_details=true on the profile. For more information about RAR constraints, refer to Rich Authorization Requests.

Mount accessor

Profiles do not have an auth mount, so Vault identifies identity aliases backed by a profile with a synthetic mount accessor assembled from the namespace ID and the profile config_id:

oauth-resource-server_<namespace_id>_<config_id>

For example, a profile with the config ID b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03 in the root namespace has the mount accessor oauth-resource-server_root_b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03.

The read, write, and list endpoints return the assembled accessor in the mount_accessor field, so you do not have to build the accessor yourself. Vault reports the same mount_accessor value for profile-backed aliases in identity and audit output, and templated policies select a profile-backed alias by its mount_accessor.

List profiles

List all OAuth Resource Server configuration profiles in the current namespace.

The response covers both local and global profiles, sorted by profile name. When a profile name exists in both local and global storage, Vault returns the local profile.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/config/oauth-resource-server

Sample response

{
  "data": {
    "keys": [
      "corporate-idp",
      "github-actions"
    ],
    "key_info": {
      "corporate-idp": {
        "config_id": "a1e4d782-5b3c-4f09-8e7a-2d9c3f6a1b04",
        "mount_accessor": "oauth-resource-server_root_a1e4d782-5b3c-4f09-8e7a-2d9c3f6a1b04"
      },
      "github-actions": {
        "config_id": "b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
        "mount_accessor": "oauth-resource-server_root_b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03"
      }
    }
  }
}

Response fields

• keys (list of strings) – Names of the profiles in the namespace, sorted alphabetically.

• key_info (map of objects) – Details for each profile, keyed by profile name. Each entry contains the config_id and mount_accessor of the profile.

When Vault cannot read the details of a listed profile, it keeps the profile name in keys, omits the profile from key_info, and returns a warning naming the profiles it skipped. If Vault cannot read any of the listed profiles, key_info is an empty map.

When the namespace contains no profiles, the endpoint returns a 404 Not Found response.

Read profile

Read the OAuth Resource Server configuration profile whose name matches the value you provide.

The response includes the profile mount_accessor. For more information, refer to Mount accessor.

Parameters

• name (string: <required>) – Name of the profile to read.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/config/oauth-resource-server/github-actions

Sample response (JWKS mode)

{
  "data": {
    "actor_claim": "act.sub",
    "audiences": ["https://github.com/my-org"],
    "authorization_details_claim": "authorization_details",
    "clock_skew_leeway": 30,
    "config_id": "b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
    "enabled": true,
    "issuer_id": "https://token.actions.githubusercontent.com",
    "jwks_uri": "https://token.actions.githubusercontent.com/.well-known/jwks",
    "jwt_type": "access_token",
    "local": false,
    "mount_accessor": "oauth-resource-server_root_b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
    "no_default_policy": false,
    "optional_authorization_details": false,
    "profile_name": "github-actions",
    "supported_algorithms": ["RS256"],
    "unique_id_claim": "jti",
    "use_jwks": true,
    "user_claim": "sub"
  }
}

Sample response (static keys mode)

{
  "data": {
    "actor_claim": "act.sub",
    "audiences": ["vault"],
    "authorization_details_claim": "authorization_details",
    "clock_skew_leeway": 0,
    "config_id": "a1e4d782-5b3c-4f09-8e7a-2d9c3f6a1b04",
    "enabled": true,
    "issuer_id": "https://idp.example.com",
    "jwt_type": "access_token",
    "local": false,
    "mount_accessor": "oauth-resource-server_root_a1e4d782-5b3c-4f09-8e7a-2d9c3f6a1b04",
    "no_default_policy": false,
    "optional_authorization_details": false,
    "profile_name": "corporate-idp",
    "public_keys": [
      {
        "key_id": "key-2026-01",
        "pem": "-----BEGIN PUBLIC KEY-----\nMIIBI..."
      }
    ],
    "supported_algorithms": ["RS256", "ES256"],
    "unique_id_claim": "jti",
    "use_jwks": false,
    "user_claim": "sub"
  }
}

Read profile by config ID

Read the OAuth Resource Server configuration profile whose config_id matches the value you provide.

The response includes the profile mount_accessor. For more information, refer to Mount accessor.

Parameters

• config_id (string: <required>) – Config ID of the profile to read.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/config/oauth-resource-server/id/a1e4d782-5b3c-4f09-8e7a-2d9c3f6a1b04

Sample response (JWKS mode)

{
  "data": {
    "actor_claim": "act.sub",
    "audiences": ["https://github.com/my-org"],
    "authorization_details_claim": "authorization_details",
    "clock_skew_leeway": 30,
    "config_id": "b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
    "enabled": true,
    "issuer_id": "https://token.actions.githubusercontent.com",
    "jwks_uri": "https://token.actions.githubusercontent.com/.well-known/jwks",
    "jwt_type": "access_token",
    "local": false,
    "mount_accessor": "oauth-resource-server_root_b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
    "no_default_policy": false,
    "optional_authorization_details": false,
    "profile_name": "github-actions",
    "supported_algorithms": ["RS256"],
    "unique_id_claim": "jti",
    "use_jwks": true,
    "user_claim": "sub"
  }
}

Sample response (static keys mode)

{
  "data": {
    "actor_claim": "act.sub",
    "audiences": ["vault"],
    "authorization_details_claim": "authorization_details",
    "clock_skew_leeway": 0,
    "config_id": "a1e4d782-5b3c-4f09-8e7a-2d9c3f6a1b04",
    "enabled": true,
    "issuer_id": "https://idp.example.com",
    "jwt_type": "access_token",
    "local": false,
    "mount_accessor": "oauth-resource-server_root_a1e4d782-5b3c-4f09-8e7a-2d9c3f6a1b04",
    "no_default_policy": false,
    "optional_authorization_details": false,
    "profile_name": "corporate-idp",
    "public_keys": [
      {
        "key_id": "key-2026-01",
        "pem": "-----BEGIN PUBLIC KEY-----\nMIIBI..."
      }
    ],
    "supported_algorithms": ["RS256", "ES256"],
    "unique_id_claim": "jti",
    "use_jwks": false,
    "user_claim": "sub"
  }
}

Create profile

Create a new OAuth Resource Server configuration profile.

Parameters

• name (string: <required>) – Name of the profile. The name must be unique across all profiles, both local and global, in the target namespace. You cannot create a local profile and a global profile with the same name.

• issuer_id (string: <required>) – The issuer identifier (iss claim) to validate against. Vault normalizes this value by trimming trailing slashes and lowercasing. The issuer_id must be unique among profiles with the same locality (local or global) in the namespace. You cannot modify issuer_id during updates.

• local (bool: false) – Requires Vault 2.2.0 or later. When set to true, Vault stores the profile in cluster-local storage. Vault never replicates local profiles to other clusters. You can write local profiles directly on a performance secondary without forwarding the request to the primary. The local field is immutable once you create the profile. You must delete and recreate the profile to change locality.

• use_jwks (bool: true) – When set to true, Vault fetches public keys from the jwks_uri. When set to false, Vault uses the static keys provided in public_keys. These two modes are mutually exclusive.

• jwks_uri (string: "") – URI to fetch public keys in JWKS format. Required when use_jwks=true. Cannot be specified when use_jwks=false.

• jwks_ca_pem (string: "") – PEM-encoded CA certificate for TLS validation of the JWKS URI connection. Only applicable when use_jwks=true.

• public_keys (list of objects: []) – List of static public keys for signature validation. Required when use_jwks=false. Cannot be specified when use_jwks=true. Each object must contain:

  • key_id (string) – The JWT Key ID (kid) for this key. Must be unique within the profile.
  • pem (string) – PEM-encoded public key. Vault accepts RSA, ECDSA, and Ed25519 keys.

• audiences (list of strings: []) – Allowed values for the aud claim. When set, Vault rejects JWTs that do not contain at least one matching audience.

• no_default_policy (bool: false) – When set to true, tokens authenticated through the profile omit the default policy unless it is applied through another mechanism. For more information about the default policy, refer to Default policy.

• optional_authorization_details (bool: false) – When set to true, allows authentication without authorization_details in the JWT for all agents using the configured profile. By default, Vault requires RAR (rich authorization requests) for the agent registry and rejects non-RAR requests. For more information about RAR constraints, refer to Rich Authorization Requests.

• user_claim (string: "sub") – The JWT claim to use as the user identifier.

• supported_algorithms (list of strings: []) – Signing algorithms to accept (for example, RS256, ES256, EdDSA). When empty, Vault accepts any algorithm supported by the key material.

• jwt_type (string: "access_token") – The type of JWT to expect. Must be access_token.

• clock_skew_leeway (int: 0) – Leeway in seconds for clock skew when validating exp, iat, and nbf claims.

• enabled (bool: true) – Whether the profile is active. Disabled profiles are not evaluated during JWT validation.

• unique_id_claim (string: "jti") – The claim that uniquely identifies a specific JWT. You cannot modify unique_id_claim during updates.

• actor_claim (string: "act.sub") – The claim that Vault should use to resolve an actor's entity.

• authorization_details_claim (string: "authorization_details") – Requires Vault 2.2.0 or later. The JWT claim that contains the authorization details for Rich Authorization Requests.

Sample payload (JWKS mode)

{
  "issuer_id": "https://token.actions.githubusercontent.com",
  "use_jwks": true,
  "jwks_uri": "https://token.actions.githubusercontent.com/.well-known/jwks",
  "audiences": ["https://github.com/my-org"],
  "user_claim": "sub",
  "supported_algorithms": ["RS256"],
  "jwt_type": "access_token",
  "clock_skew_leeway": 30
}

Sample payload (static keys mode)

{
  "issuer_id": "https://idp.example.com",
  "use_jwks": false,
  "public_keys": [
    {
      "key_id": "key-2026-01",
      "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhki..."
    }
  ],
  "audiences": ["vault"],
  "supported_algorithms": ["RS256"],
  "jwt_type": "access_token"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/config/oauth-resource-server/github-actions

A successful create returns a 200 OK response containing the stored profile, including the generated config_id and the assembled mount_accessor. You do not need a follow-up read to obtain config_id or mount_accessor.

If validation produces warnings (such as a non-HTTPS issuer or an unreachable JWKS URI), Vault returns the warnings alongside the profile data.

Sample response

{
  "data": {
    "actor_claim": "act.sub",
    "audiences": ["https://github.com/my-org"],
    "authorization_details_claim": "authorization_details",
    "clock_skew_leeway": 30,
    "config_id": "b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
    "enabled": true,
    "issuer_id": "https://token.actions.githubusercontent.com",
    "jwks_uri": "https://token.actions.githubusercontent.com/.well-known/jwks",
    "jwt_type": "access_token",
    "local": false,
    "mount_accessor": "oauth-resource-server_root_b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
    "no_default_policy": false,
    "optional_authorization_details": false,
    "profile_name": "github-actions",
    "supported_algorithms": ["RS256"],
    "unique_id_claim": "jti",
    "use_jwks": true,
    "user_claim": "sub"
  },
  "warnings": null
}

Update profile

Update an existing OAuth Resource Server configuration profile. Updates only the fields you include in the request body; omitted fields retain their current values.

Parameters

The parameters are the same as Create profile, except:

• issuer_id is optional on update.
• You cannot change issuer_id, local, or unique_id_claim after creating the profile. Omit those parameters on updates or pass the value already stored. Vault returns an error if you attempt to change them.

When switching between key modes (toggling use_jwks), Vault clears the fields from the previous mode automatically. For example, switching from use_jwks=true to use_jwks=false clears the stored jwks_uri.

Sample payload

{
  "audiences": ["https://github.com/my-org", "https://github.com/other-org"],
  "clock_skew_leeway": 60
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/config/oauth-resource-server/github-actions

A successful update returns a 200 OK response containing the updated profile, in the same shape as the create response. The config_id and mount_accessor remain stable across updates.

Delete profile

Delete the OAuth Resource Server configuration profile whose name matches the value you provide. Deleting a non-existent profile succeeds without error.

Parameters

• name (string: <required>) – Name of the profile to delete.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/config/oauth-resource-server/github-actions

A successful delete returns a 204 No Content response with no body.