Skip to content
Ctrl/⌘ K

Getting started

Service accounts

Create service accounts for automated workloads and manage their credentials.

Exchange a service-account credential

Use a service account for an automated workload. Use a human API key for a member-operated integration, or MCP OAuth when an AI client acts with a member's approval.

Create the account in Settings → Service accounts, select only the permissions the workload needs, and create a credential. Move the returned token_endpoint, client_id, and client_secret directly into the workload's secret manager. The plaintext secret is present only in the creation response.

Set YEP_TOKEN_ENDPOINT, YEP_CLIENT_ID, and YEP_CLIENT_SECRET, then request an access token:

Request cURL 
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"

Never send the client secret to a Search API endpoint, browser code, URL, source-control repository, log, or another service account.

Request a token in application code

Request TypeScript 
const body = new URLSearchParams({
  client_id: process.env.YEP_CLIENT_ID!,
  client_secret: process.env.YEP_CLIENT_SECRET!,
  grant_type: "client_credentials",
});
const response = await fetch(process.env.YEP_TOKEN_ENDPOINT!, { method: "POST", body });
if (!response.ok) throw new Error(`Token endpoint returned ${response.status}`);
const token = await response.json();

The token response provides its lifetime. Cache the access token in workload memory, request a replacement before expiry, and ensure concurrent requests share one refresh. After an unexpected 401, fetch one new token and retry once; repeated rejection requires operator action.

Send the access token

Send the access token as the Bearer credential. Do not send the client secret.

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

Set permissions and boundaries

Each access token is workspace-bound. The service-account permissions selected at creation must authorize the requested operation, and resource ownership boundaries still apply. Revoking the account invalidates credentials issued for that identity.

Use separate service accounts for workloads that need different permissions, ownership, limits, or revocation schedules. Do not share one identity across unrelated applications.

Rotate without an outage

  1. Create a replacement service account with the required permissions.
  2. Recreate account-specific limits and move work owned by the previous identity.
  3. Create and deploy the replacement credential.
  4. Verify token exchange and one intended Yep request.
  5. Revoke the previous service account.

If a credential may have leaked, revoke its service account before creating the replacement. Revocation is the boundary that invalidates all credentials for that service-account identity.

Commands