Management keys

When to use a management key

A management key is a workspace identity for an automated workload, such as a scheduled job or a backend service. It has a client ID and a client secret, which it exchanges for an access token, and it calls the Search API with that token.

Use a management key when no person runs the workload, so that its access does not depend on one member's API key. Use a personal API key for an integration that a member operates, and MCP when an AI client acts with a member's approval.

Create a management key

In Dashboard → Management keys, select Create management key, name it after the workload, and select its permissions. Then select Create credential on the new management key. By default, only workspace administrators can do this, and Yep may ask you to sign in again first.

The credential holds three values: token_endpoint, client_id and client_secret. Store them in the workload's secret manager. The client secret is shown once and cannot be retrieved later.

Request an access token

Set YEP_TOKEN_ENDPOINT, YEP_CLIENT_ID and YEP_CLIENT_SECRET from the credential, then post them with the OAuth client credentials grant to the credential's token endpoint, which is separate from the Search API.

curl --request POST "$YEP_TOKEN_ENDPOINT" \
  --data-urlencode "client_id=$YEP_CLIENT_ID" \
  --data-urlencode "client_secret=$YEP_CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials"

The response contains access_token and expires_in, the token's lifetime in seconds.

Call the API

Send the access token as a Bearer token, as Authentication describes for API keys. Send the client secret only to the token endpoint.

curl --get "https://platform.yep.com/api/v1/search" \
  --header "Authorization: Bearer $YEP_ACCESS_TOKEN" \
  --data-urlencode "query=carbon border tax 2026"

Token and secret lifetime

An access token expires after expires_in seconds. Keep it in the workload's memory, request a new one shortly before it expires, and let concurrent requests share one refresh. If a request returns 401, request a new token and retry once.

Yep sets no expiry on a client secret. To rotate it, create another credential on the same management key, deploy it, and confirm that a token request and a search succeed. Earlier secrets keep working until you revoke the management key, so to retire them, move the workload to a new management key and revoke the old one.

Permissions and scope

A management key belongs to one workspace, and every token it receives is bound to that workspace. Its only permission is Search, which allows search requests. It cannot manage API keys or connect to MCP. You can grant only permissions that you hold yourself, and they cannot be changed after creation.

Usage reports a management key's requests separately, and Limits can set a spend limit for it. Use a separate management key for each workload so that each can be limited or revoked on its own.

Revoke a management key

Select Revoke management key in Dashboard → Management keys. Revocation deletes the management key and all of its credentials: the secrets can no longer obtain tokens, and Yep refuses tokens already issued to it. Revocation cannot be undone.

If a secret may have leaked, revoke the management key first, then create a replacement and deploy its credential.

Common errors

Every Search API error body carries request_id, which equals the X-Request-ID response header. Include it when you contact support.

• A failed token request comes from the token endpoint, not from the Search API, and has no request_id. Check YEP_TOKEN_ENDPOINT, YEP_CLIENT_ID and YEP_CLIENT_SECRET.
• 401 with reason authentication_required — the token is missing, expired, or not a Yep access token.
• 403 with reason permission_denied — the operation needs a permission that management keys do not have.
• 402 and 429 — see Errors, limits, and billing.