velgent.

#Setting up OAuth clients

An OAuth client lets a caller exchange a client_id + client_secret for a short-lived access token instead of sending a static API key on every request. Reach for it when you want the credential on the wire to expire quickly, or when the calling platform speaks OAuth2 client_credentials natively.

Clients are self-service from the admin console. This page covers creating, rotating, and revoking them. For the token exchange and how to call the API with the token, see Authentication → OAuth 2.0.

API key or OAuth client?

Both are valid and can coexist on the same tenant. API keys are the simplest path for server-to-server calls. OAuth clients add a token-exchange step so the per-request credential is short-lived — use them when your security policy or integration platform calls for it.

#Prerequisites

Sign in to admin.velgent.com as:

  • org_admin — manages your own tenant's clients.
  • root — Velgent platform staff; pick the target tenant from the sidebar org picker first.

#Create a client

  1. Sign in to admin.velgent.com.
  2. Click OAuth clients in the left sidebar.
  3. Type a descriptive name — e.g. copilot-studio, partner-integration. The name appears in audit logs.
  4. Click Create client.

Two values appear in a one-time reveal banner:

client_id      velgent_client_xxxxxxxxxxxxxxxx
client_secret  velgent_secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Copy the secret now

The client_secret is shown only once — after you dismiss the banner it cannot be recovered (only a short prefix is stored). The client_id is not secret and stays visible in the table, so you can always read it later; the secret you cannot. If you lose the secret, rotate the client to get a new one.

Store both the same way you store any production secret — a secrets manager or an environment variable your application reads at start. Never in source control.

#Use the client

Exchange the credentials for a token, then call the API with that token:

# 1. Get a short-lived access token (default 1 hour)
curl https://aiengine.velgent.com/api/v1/oauth/token \
  -u "$VELGENT_CLIENT_ID:$VELGENT_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

# 2. Call the API with the returned access_token
curl https://aiengine.velgent.com/api/v1/summarise \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "operation": "summarise_text", "text": "…" }'

Re-request a token when the old one expires — there are no refresh tokens in this flow. Full details on Authentication.

#Rotate a client

Rotation is one click with a built-in grace window, so you swap secrets with zero downtime:

  1. On the client's row, click Rotate. Confirm the prompt.
  2. A new client_id + client_secret are generated and shown once — copy both.
  3. The old client keeps issuing tokens for a grace window — 7 days by default. Its row shows an expiring badge and an Expires date.
  4. Deploy the new credentials wherever your application reads them. Confirm the cutover in Activity logs.
  5. Let the old client expire automatically, or click Revoke now to close the window early.

After expiry (or revoke), the old client can no longer mint tokens.

Tokens already issued

Rotating or revoking a client stops new tokens from being issued immediately. Access tokens that were already minted stay valid until they expire — at most one hour. For a compromised client, revoke it and treat the ≤1h window as the exposure.

#Revoke a client

If a client_secret leaks, or you're decommissioning an integration:

  1. OAuth clients → find the row (match the client_id) → Revoke.
  2. No new tokens can be minted with it from that moment.
  3. Create a replacement and deploy if the integration is still needed.

#What a client sees

An access token inherits the full surface of the public API (/api/v1/*) for its tenant — same access as an API key today. Per-operation scoping is reserved but not yet enforced. A token does not grant access to other tenants' data, the admin console, or the admin API at /api/admin/*.

#Audit + activity

Every client lifecycle action (create, rotate, revoke) is recorded in the admin audit trail, and token-authenticated API calls show up in Activity logs alongside key-authenticated calls.