/sys/config/oauth-resource-server

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.

List profiles

List all OAuth Resource Server configuration profile names in the current namespace.

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": [
      "github-actions",
      "corporate-idp"
    ]
  }
}

Read profile

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

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": {
    "config_id": "b2f5c891-3a7d-4e12-9f8a-1c6d4e7b2a03",
    "profile_name": "github-actions",
    "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"],
    "no_default_policy": false,
    "user_claim": "sub",
    "supported_algorithms": ["RS256"],
    "jwt_type": "access_token",
    "clock_skew_leeway": 30,
    "enabled": true
  }
}

Sample response (static keys mode)

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

Create profile

Create a new OAuth Resource Server configuration profile.

Parameters

• name (string: <required>) – Name of the profile. The name must be unique within the target namespace for the request.

• issuer_id (string: <required>) – The issuer identifier (iss claim) to validate against. Vault normalizes this value by trimming trailing slashes and lowercasing. Each issuer_id must be unique across all profiles in the namespace.

• 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.

• 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.

• 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). 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 or transaction_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.

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 204 No Content response with no body. If validation produces warnings (such as a non-HTTPS issuer or an unreachable JWKS URI), the response includes the warnings.

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.

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 204 No Content response with no body.

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.