SPIFFE auth method (API)

Use the SPIFFE plugin to support authentication with JWT or x.509 based SPIFFE SVIDs. The example code below assumes you mounted the SPIFFE plugin at /auth/spiffe. Since it is possible to enable auth methods at any location, please update your API calls accordingly.

Create configuration

Configure or refresh the SPIFFE trust domain and associated trust bundle for the plugin. To refresh an existing cached bundle, call the endpoint with an empty payload.

If you use profiles that fetch the trust bundle from a remote endpoint, Vault immediately fetches a trust bundle when you create the configuration unless you set defer_bundle_fetch to true. If the initial fetch fails, Vault returns an error and rolls back any configuration changes.

Request parameters

• trust_domain (string: <required>) - The SPIFFE trust domain used by the plugin. You can omit the spiffe:// prefix.
• profile (string: <required>) - The profile to use to fetch the trust bundle, see profile section below for associated parameters based on the selected profile. Valid values are static,
• profile (string: <required>) - Set the profile type and fetch mechanism for the profile used to fetch the trust bundle. Must be one of:
  • https_spiffe_bundle - fetch the trust bundle in JWKS format from a SPIFFE endpoint.
  • https_web_bundle - fetch the trust bundle in JWKS format from an HTTPS endpoint.
  • https_web_pem - fetch a valid X.509 certificate as the trust bundle from an HTTPS endpoint.
  • static - use the trust bundle explicilty configured in the profile definition.
• audience (array: []) - A list of allowed audience values for JWT based SVIDs. Vault rejects any JWT-based SVIDS not provided in the audience list. Leave audience empty to deny all JWT-based SVIDS.
• defer_bundle_fetch (bool: false) - Tells Vault not to fetch the remote trust bundle to validate the configuration. For example, you can set defer_bundle_fetch to true when you need to update your Vault configuration before the remote endpoint is available.

Profile parameters

In addition to the common request parameters, you must set the following profile-specific parameters based on the value of profile.

Static profile (static)

Provide the trust bundle directly as part of the configuration.

• bundle (string: <required>) - A PEM encoded X.509 certificate or a JWKS document following the SPIFFE Trust Domain and Bundle specification.

Remote HTTPS Web PEM profile (https_web_pem)

Provide HTTPS connection details so Vault can fetch an X.509 certificate to use as a trust bundle.

• endpoint_url (string: <required>) - URL of an HTTPS server that can provide the PEM encoded X.509 certificate.
• endpoint_root_ca_truststore_pem (string: "") - A PEM encoded X.509 certificate Vault can use as a root CA to validate the TLS certificate provided by the remote server. Leave endpoint_root_ca_truststore_pem unset to use the system root CAs.

Remote HTTPS Web Bundle profile (https_web_bundle)

Provide HTTPS connection details so Vault can fetch a SPIFFE bundle in JWKS format from a remote server. To use the remote HTTPS web bundle profile with a SPIRE server, the server must support a SPIRE Federation API endpoint of type https_web.

• endpoint_url (string: <required>) - URL of an HTTPS server that can provide the PEM encoded X.509 certificate.
• endpoint_root_ca_truststore_pem (string: "") - A PEM encoded X.509 certificate Vault can use as a root CA to validate the TLS certificate provided by the remote server. Leave endpoint_root_ca_truststore_pem unset to use the system root CAs.

Remote HTTPS SPIFFE Bundle profile (https_spiffe_bundle)

Provide HTTPS connection details so Vault can fetch a SPIFFE bundle in JWKS format from a remote SPIFFE endpoint. To use the remote HTTPS SPIFFE profile with a SPIRE server, the server must support a SPIRE Federation API endpoint of type https_spiffe.

• endpoint_spiffe_id (string: <required>) - The SPIFFE ID of the remote endpoint to connect to.
• endpoint_url (string: <required>) - URL of an HTTPS server that can provide the PEM encoded X.509 certificate.
• bundle (string: <required>) - A SPIFFE bundle in JKWS format that Vault can use as a trust anchor to validate the TLS certificate from the SPIFFE endpoint.

Sample payload

{
  "trust_domain": "example.org",
  "profile": "https_web_bundle",
  "endpoint_url": "https://spire.example.org",
  "endpoint_root_ca_truststore_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "audience": ["vault"]
}

Read configuration

Fetch the SPIFFE configuration details and relevant metadata about the currently cached trust bundle.

Request parameters

None.

Sample response

{
  "cached_bundle_config_version": 1,
  "cached_bundle_fetched_at": "2025-09-18T14:02:21.730308-04:00",
  "cached_bundle_refresh_hint": "15m0s",
  "cached_bundle_sequence_number": 11,
  "endpoint_root_ca_truststore_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "endpoint_url": "https://192.168.1.65:8443",
  "profile": "https_web_bundle",
  "trust_domain": "spiffe://test.dadgarcorp.org",
  "version": 1
}

Create role

Create or update a named role that maps SPIFFE IDs to Vault policies.

Different roles may not have the same workload ID patterns. Vault uses standard policy priority matching logic to determine the appropriate role when there are overlapping patterns across different roles (e.g. role1 has team1/* and role2 has team1/service1).

Path parameters

• name (string: <required>) - The unique name of the SPIFFE role you want to update.

Request parameters

• display_name (string: "<name>") - The human-readable name for tokens issued when authenticating against the role. Defaults to the value provided for name.

• workload_id_patterns (array: <required>) - A comma separated list of patterns that match an incoming workload ID associated with the SPIFFE role. You can find the workload ID by stripping the trust domain prefix and slash separator from the associated SPIFFE ID. You can use the following special characters with the workload ID:

  • * - matches to any number of characters at the end of an ID to perform prefix matching
  • + - matches to any number of characters within a single path segment to perform wildcard matching.

• token_ttl (integer: 0 or string: "") - The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.
• token_max_ttl (integer: 0 or string: "") - The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.
• token_policies (array: [] or comma-delimited string: "") - List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.
• policies (array: [] or comma-delimited string: "") - DEPRECATED: Please use the token_policies parameter instead. List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.

• token_bound_cidrs (array: [] or comma-delimited string: "") - List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.
• token_explicit_max_ttl (integer: 0 or string: "") - If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl and token_max_ttl would otherwise allow a renewal.
• token_no_default_policy (bool: false) - If set, the default policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies.
• token_num_uses (integer: 0) - The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.
• token_period (integer: 0 or string: "") - The maximum allowed period value when a periodic token is requested from this role.
• token_type (string: "") - The type of token that should be generated. Can be service, batch, or default to use the mount's tuned default (which unless changed will be service tokens). For token store roles, there are two additional possibilities: default-service and default-batch which specify the type to return unless the client requests a different type at generation time. For machine based authentication cases, you should use batch type tokens.

Sample payload

{
  "workload_id_patterns": ["service1", "team1/*", "team2/+/service1"],
  "display_name": "example-role",
  "token_policies": ["spiffe-service1"]
}

Read role

Read the named SPIFFE role.

Path parameters

• name (string: <required>) - The unique name of the SPIFFE role you want to read.

Sample response

{
  "alias_metadata": {},
  "display_name": "example-role",
  "name": "example-role",
  "token_bound_cidrs": [],
  "token_explicit_max_ttl": 0,
  "token_max_ttl": 0,
  "token_no_default_policy": false,
  "token_num_uses": 0,
  "token_period": 0,
  "token_policies": [
    "spiffe-service1"
  ],
  "token_ttl": 0,
  "token_type": "default",
  "workload_id_patterns": [
    "service1",
    "team1/*",
    "team2/+/service1"
  ]
}

Delete role

Delete the named SPIFFE role.

Path parameters

• name (string: <required>) - The unique name of the SPIFFE role you want to delete.

List roles

List the names of all SPIFFE roles.

Request parameters

None.

Sample response

{
  "keys": [
    "example-role"
  ]
}

Login with SPIFFE ID

Authenticate a client using a SPIFFE JWT or x.509 SVID. To use JWT, set the SVID in the Authorization header as the bearer token and set the Authorization header as a passthrough request header in the SPIFFE backend.

Request parameters

• role (string: "") - The name of the role to use for authentication. Leave role unset to have Vault iterate over all configured roles.
• type (string: "auto") - Set the SVID source for authentication. Must be one of:
  • auto - use JWT SVIDs if provided, otherwise use SVIDs from the peer x.509 certificate.
  • cert - only use SVIDs from x.509 certificates.
  • jwt - only use JWT SVIDs.