> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/rest-auth-credentials.md). # REST Auth Credentials Configure reusable authentication for Send REST Payload and Send XML Payload actions in Lifecycle Management ### Overview REST Auth Credentials provide centralized, reusable authentication configurations for [Send REST Payload](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/send-rest-request.md) and [Send XML Payload](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/send-xml-payload.md) actions in Lifecycle Management workflows. Instead of configuring authentication directly in each action, you can create named credential sets that multiple actions can reference. Benefits: * **Reuse**: Share one authentication configuration across multiple actions * **Security**: Sensitive fields (passwords, tokens, secrets) are encrypted at rest * **Centralized management**: Update credentials in one place; all referencing actions use the latest configuration * **Audit**: Track credential usage and creation history ### Supported Authentication Types | Auth Type | Description | Use Case | | --------------------------- | --------------------------------------------------------- | ----------------------------------------------------- | | **Header** | Custom authorization header value | API keys, custom token formats | | **Basic** | HTTP Basic authentication (username/password) | Legacy APIs, Basic authentication endpoints | | **Bearer** | Bearer token authentication | JWT tokens, API tokens | | **Login to Bearer** | Two-step: login request, then extract token from response | APIs requiring session-based auth | | **OAuth2** | OAuth 2.0 client credentials flow | Modern APIs with OAuth2 support | | **OAuth2 (Password Grant)** | OAuth 2.0 resource owner password credentials grant | Targets that expose no other machine-to-machine grant | | **None** | No authentication header added | Public APIs, pre-authenticated endpoints | ### Configuring REST Auth Credentials #### Using the Veza UI 1. Navigate to **Lifecycle Management** > **Settings** 2. Select the **Credentials** tab 3. Click **New REST/XML Credentials** to add a new credential 4. Enter a **Name** for the credential 5. Select the **Auth Type** and complete the required fields (see [Auth Type Configuration](#auth-type-configuration)) 6. For the **OAuth2** and **OAuth2 (Password Grant)** auth types, enter any scopes the token endpoint requires in **Scope (Optional)**, separated by spaces (see [OAuth2](#oauth2)) 7. Optionally set a default URL and method in **URL (Optional)** and **Method (Optional)** (actions can override these values) 8. For the **Login to Bearer**, **OAuth2**, and **OAuth2 (Password Grant)** auth types, optionally set a **Token Reuse Window (Seconds)** (see [Token Reuse Window](#token-reuse-window)) 9. Click **Save** {% hint style="info" %} The **URL (Optional)** and **Method (Optional)** fields on credentials are defaults. When a Send REST Payload action specifies its own **URL** or **HTTP Method**, those values take precedence over the credential defaults. {% endhint %} #### Using the REST API REST Auth Credentials are managed via the Lifecycle Management API: **Create a credential:** ```bash curl -X POST "https://{VEZA_URL}/api/private/lifecycle_management/rest_auth_credentials" \ -H "Authorization: Bearer {API_KEY}" \ -H "Content-Type: application/json" \ --data '{ "value": { "name": "My API Credential", "auth_type": "BEARER", "bearer_settings": { "token": "eyJhbGciOiJIUzI1NiIs..." }, "url": "https://api.example.com/v1", "method": "POST" } }' ``` **List credentials:** ```bash curl "https://{VEZA_URL}/api/private/lifecycle_management/rest_auth_credentials" \ -H "Authorization: Bearer {API_KEY}" ``` **Get a single credential:** ```bash curl "https://{VEZA_URL}/api/private/lifecycle_management/rest_auth_credentials/{CREDENTIAL_ID}" \ -H "Authorization: Bearer {API_KEY}" ``` **Update a credential:** ```bash curl -X PATCH "https://{VEZA_URL}/api/private/lifecycle_management/rest_auth_credentials/{CREDENTIAL_ID}" \ -H "Authorization: Bearer {API_KEY}" \ -H "Content-Type: application/json" \ --data '{ "value": { "id": "{CREDENTIAL_ID}", "name": "Updated Credential Name", "bearer_settings": { "token": "new-token-value" } } }' ``` **Delete a credential:** ```bash curl -X DELETE "https://{VEZA_URL}/api/private/lifecycle_management/rest_auth_credentials/{CREDENTIAL_ID}" \ -H "Authorization: Bearer {API_KEY}" ``` {% hint style="warning" %} Credentials referenced by published policy versions cannot be deleted. Remove the credential reference from all actions in published policies first. {% endhint %} ### Auth Type Configuration #### Header Provides a custom authorization header value. Use this for API keys or non-standard token formats. | Field | Required | Description | | ------------ | -------- | -------------------------------------------------- | | `full_value` | Yes | Complete header value (e.g., `ApiKey sk-prod-xyz`) | The value is sent as the `Authorization` header on each request. #### Basic HTTP Basic authentication with username and password. | Field | Required | Description | | ----------- | -------- | ------------------------------------------- | | `user_name` | Yes | Authentication username | | `password` | Yes | Authentication password (encrypted at rest) | Veza constructs the `Authorization: Basic {base64(username:password)}` header automatically. #### Bearer Bearer token authentication. | Field | Required | Description | | ------- | -------- | -------------------------------------- | | `token` | Yes | Bearer token value (encrypted at rest) | Veza constructs the `Authorization: Bearer {token}` header automatically. #### Login to Bearer Two-step authentication: perform a login request, then extract a bearer token from the response. Use this for APIs that require an initial authentication step before issuing a session token. | Field | Required | Description | | ------------------------ | -------- | -------------------------------------------------------------------------- | | `login_url` | Yes | URL to send the login POST request | | `login_payload_json` | Yes | JSON body for the login request (encrypted at rest) | | `bearer_token_attribute` | Yes | Dot-notation path to the token in the login response (e.g., `value.token`) | **How it works:** 1. Veza sends a POST request to `login_url` with `login_payload_json` as the body 2. The JSON response is parsed using `bearer_token_attribute` to extract the token 3. The extracted token is used as a Bearer token for the actual REST request **Example:** If the login API returns: ```json { "value": { "token": "eyJhbGciOiJIUzI1NiIs...", "expires_in": 3600 } } ``` Set `bearer_token_attribute` to `value.token` to extract the token. #### OAuth2 OAuth 2.0 client credentials flow. | Field | Required | Description | | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `client_id` | Yes | OAuth2 client ID | | `client_secret` | Yes | OAuth2 client secret (encrypted at rest) | | `authentication_method` | Yes | How to send credentials: `FORM` or `BASIC` (see below) | | `auth_url` | No | Token endpoint URL. Defaults to `{credential_url}/oauth2/token` if not specified | | `scope` | No | Space-delimited list of scopes to request. Sent as the `scope` parameter on the token request only when set | | `ca_certificate_base64` | No | Base64-encoded CA certificate for the OAuth2 token endpoint, if it uses a self-signed or internal CA | Veza performs the client credentials flow to obtain an access token, then uses it as a Bearer token for the REST request. Some token endpoints reject a client credentials request that has no scope. Microsoft Entra ID, for example, expects the target resource's `.default` scope, such as `https://.operations.dynamics.com/.default` for Dynamics 365 finance and operations apps. Check the token endpoint's documentation for the scope value to use. {% hint style="info" %} `ca_certificate_base64` only applies to the **OAuth2 token endpoint** (the `auth_url` connection). It does not affect TLS verification for the main REST request to your target API. If the target API itself uses an internal CA certificate, you must configure that certificate in the Insight Point's truststore. See [Custom Certificate Configuration](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/ova-v2.md#custom-certificate-configuration) (OVA) or [Using Custom Certificates](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point/insight-point-install-script.md#using-custom-certificates) (install script). {% endhint %} **Choosing an authentication method:** * **`FORM`** (default): Sends `client_id` and `client_secret` as form-encoded parameters in the POST body alongside `grant_type=client_credentials`, plus `scope` when set. Use this when the token endpoint expects credentials in the request body. * **`BASIC`**: Sends credentials in the `Authorization: Basic base64(client_id:client_secret)` header, with `grant_type=client_credentials`, plus `scope` when set, in the POST body. Use this when the token endpoint requires HTTP Basic authentication. Check your target API's OAuth2 documentation to determine which method it supports. Both conform to [RFC 6749 §2.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1). When in doubt, try `FORM` first as it is the default and more widely supported. #### OAuth2 (Password Grant) OAuth 2.0 resource owner password credentials grant ([RFC 6749 §4.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3)). Veza posts a resource owner's username and password to the token endpoint and uses the returned access token as a Bearer token for the REST request. | Field | Required | Description | | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_name` | Yes | Resource owner username | | `password` | Yes | Resource owner password (encrypted at rest) | | `authentication_method` | Yes | How to send the client credentials: `FORM` or `BASIC`. Applies only when `client_id` is set | | `auth_url` | No | Token endpoint URL. Defaults to `{credential_url}/oauth2/token` if not specified | | `client_id` | No | OAuth2 client ID. Omit for a public client | | `client_secret` | No | OAuth2 client secret (encrypted at rest) | | `scope` | No | Space-delimited list of scopes to request | | `ca_certificate_base64` | No | Base64-encoded CA certificate for the token endpoint, if it uses a self-signed or internal CA. Applies to the `auth_url` connection only, as described under [OAuth2](#oauth2) | A public client sends neither `client_id` nor `client_secret`. The resource owner's username and password are what authenticate the request. When `client_id` is set, `authentication_method` decides whether the client credentials travel in the `Authorization` header (`BASIC`) or in the request body (`FORM`), as described under [OAuth2](#oauth2). {% hint style="warning" %} This grant sends a user's password to the token endpoint in the request body, and OAuth 2.1 deprecates it. Use **OAuth2** wherever the target supports client credentials. Select this type only for targets that expose no other machine-to-machine grant. Use an HTTPS token endpoint. Veza logs an informational message when `auth_url` is plain `http` and then sends the request anyway, so nothing stops a misconfigured credential from putting the password on the wire as plain text. {% endhint %} #### None No authentication header is added to the request. Use this when the target API is public or when authentication is handled through other means (e.g., network-level security, pre-shared keys in URL parameters). **None** is also the only way to save a Send REST Payload or Send XML Payload action whose **Authorization Header (Legacy)** field is empty. Both actions skip the non-empty check on that field only when the selected credential is this type; without it, validation requires a header value. ### Token Reuse Window A Lifecycle Management policy runs one job per identity, and by default every job fetches its own token. A policy that touches 500 identities makes 500 requests to the target's token endpoint. Set **Token Reuse Window (Seconds)** on a credential to reuse one fetched token across the jobs in a policy run instead of fetching a new one for each job. | Setting | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Token Reuse Window (Seconds)** | How long Veza reuses a fetched token before fetching another. Range: 0–172800 (48 hours). `0` (the default) fetches a token for every job. | The field applies only to the auth types that fetch a token per job: **Login to Bearer**, **OAuth2**, and **OAuth2 (Password Grant)**. The other types carry a static credential and have no token to fetch, so Veza does not display the field for them and rejects a nonzero value set through the API. Changing a credential to a static auth type resets the window to `0` when you save. In the private Lifecycle Management API described above, this setting is the `token_cache_ttl_seconds` field. The credential list does not show the window; use the credential's edit panel to read or change it. The window applies to both the [Send REST Payload](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/send-rest-request.md) and [Send XML Payload](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/send-xml-payload.md) actions, in provisioning policies and in Access Requests, whether the action runs in the control plane or through an Insight Point. An action's **Test Connection** check uses it too, so a test can succeed on a token cached earlier rather than proving the credential still works. {% hint style="warning" %} Veza does not detect a token that the target has expired or revoked. Nothing inspects the target's response, so a token that stops working mid-window keeps being used, and every job on that credential fails until the window elapses. Set the window below the lifetime the target gives its tokens; the 48-hour maximum is too long for most targets. {% endhint %} #### Choosing a Window Start from the target's own token lifetime and stay well inside it. A window needs only to outlast a single policy run: after it does, a longer window saves no further token requests while leaving a revoked token in play for longer. Veza reuses a token for exactly the number of seconds you set, with no safety margin subtracted. Reuse is not tenant-wide: Veza can fetch more than one token per window, and an Insight Point deployment can account for several. Size any rate-limit headroom for a small number of token requests per window rather than exactly one. If the target rate-limits token issuance, a policy run without a window fails at the authentication step rather than at the API call: nothing is provisioned, and the error points at authentication instead of at request volume. #### Changing the Window A new value takes effect on the next job, but it does not discard the token cached under the old value. Veza caches a token against the window it was fetched under, so writing any different number, including `0`, moves to an entry with nothing cached and the next job fetches a fresh token. This matters when you are recovering from a revoked credential. To force a fresh token: 1. Set **Token Reuse Window (Seconds)** to `0` and save. 2. Re-run the policy. Each job now fetches its own token. 3. To turn reuse back on, either wait for the old window to elapse or set a different number of seconds. Restoring the number you were running with moments ago can hand out the same dead token again. Rotating a secret on the credential in Veza needs no such step: Veza keys a cached token to the authentication material it was fetched with, so a rotated secret is not served a token minted from the old one. ### Using Credentials in Actions When configuring a [Send REST Payload](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/send-rest-request.md) action in a Lifecycle Management policy: 1. In the action configuration, select a credential from the **Auth Credentials** dropdown 2. The credential provides the authentication header and optional default URL/method 3. The action's **URL** and **HTTP Method** settings override the credential defaults when specified {% hint style="info" %} REST Auth Credentials handle *how* to authenticate requests. To control *where* requests execute from (control plane versus Insight Point), configure the **Data Source** field separately. See [Custom Application with Send REST Payload](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/oaa-send-rest-payload.md) for Insight Point routing. {% endhint %} {% hint style="warning" %} The **Authorization Header (Legacy)** field on the Send REST Payload action is deprecated and appears only on actions that already have an inline header. Migrate existing configurations to use REST Auth Credentials for centralized management and encrypted storage. {% endhint %} ### Permissions | Operation | Required Role | | ---------------------- | --------------- | | View credentials | Admin, Operator | | Create, Update, Delete | Admin | ### See Also * [Send REST Payload Action](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions/send-rest-request.md): Action configuration and payload options * [Custom Application with Send REST Payload](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/oaa-send-rest-payload.md): Route requests through Insight Points for on-premises targets * [Transformers](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/transformers.md): Attribute transformation syntax for dynamic URLs and payloads --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/rest-auth-credentials.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.