Client credentials and provider keys

Create, check, replace and revoke Wavemaker developer credentials, sign in with OAuth, and save your own provider keys so those models bill your provider account.

Updated 2026-10-22

Wavemaker uses two kinds of secret. A Wavemaker credential lets a program act in one workspace with the scopes you chose. A provider key is your own account with a model provider, such as OpenAI or ElevenLabs; once saved, that provider's models run on your key and the provider bills you. This page covers creating, checking, replacing and revoking both.

Create a developer credential

In the web app, open Connections and choose the Developer setup tab.
Under Developer credentials, select Create credential. The button appears only when your own session has write access.
Enter a Name of up to 100 characters, for example "Nightly render job".
Choose Expires in: 1 day, 7 days (the default) or 30 days.
Choose the permissions. Read projects and results is always included. Add Create and edit source, Run work or Publish versions as needed.
Select Create credential.
Copy the credential from the Save your credential dialog and store it in a secret manager or a private file. This is the only time the full credential is shown; closing the dialog removes it from the page.

You can grant only permissions your own account already has. Each choice is listed only when your session holds that scope.

Check that it worked

Call the identity endpoint with the new credential:

curl --fail-with-body \
  --header "Authorization: Bearer $WAVEMAKER_KEY" \
  https://api.wavemaker.io/v1/identity
# → 200 {"ok": true, "data": {"schema": "wmcore.identity/1", "workspace": "...",
#        "subject": "...", "credential": "...", "kind": "api_key", "mode": "live",
#        "scopes": ["read", "run", "write"], "projects": null, "expires_at": 1793000000.0}, ...}

Field	Meaning
`workspace`	The workspace every call with this credential reads, writes and charges
`credential`	The credential's id, never its secret
`kind`	`api_key` for a developer credential, `oauth` for an app sign-in
`mode`	`live`, or `test` for a test workspace whose credits are not real money
`scopes`	What the credential may do
`projects`	`null` means every project in the workspace
`expires_at`	Unix seconds when the credential stops working

A 401 unauthenticated reply means the credential is missing, expired or revoked.

Scopes

Scope	Label in the web app	What it allows
`read`	Read projects and results	View projects, sessions, jobs and results; the `search`, `read` and `watch` tools
`write`	Create and edit source	Create and edit files, upload media, cancel jobs; the `write` and `deliver` tools
`run`	Run work	Create sessions and post turns; the `generate`, `edit`, `compose`, `listen`, `compare`, `review` and `run` tools
`publish`	Publish versions	Publish versions and community listings

Most integrations need read, write and run. A credential without run can read and organize work but cannot generate; a call outside its scopes is refused scope_denied (403).

Older credentials may carry the agent scope. The session API accepts agent in place of run, so those credentials keep working. New credentials don't need it.

Use a credential

Send it as a bearer token on every request:

GET /v1/identity HTTP/1.1
Host: api.wavemaker.io
Authorization: Bearer YOUR_CREDENTIAL

Send credentials only in the Authorization header. Never put one in a URL, a graph, a prompt, shared feedback or browser code.
For curl, keep the header in a private config file and pass --config instead of typing the secret on the command line.
The Python, TypeScript and Go clients take the credential when you create the client. They refuse a plain-HTTP origin other than your own machine, and they never follow redirects. See Python, TypeScript and Go clients.

Credential states

The Developer credentials table lists each credential's Name, Access, Expires and Status.

Status	Meaning	What to do
`current`	Works until its expiry	Nothing
`expired`	Its lifetime has passed; requests get `401 unauthenticated`	Select Replace to issue a new one
`revoked`	It was revoked or replaced; requests get `401 unauthenticated`	Use the replacement, or create a new credential

Credentials always expire. The longest lifetime you can choose is 30 days, so plan to replace a credential before its date.

Replace a credential

In Connections › Developer setup, find the credential and select Replace.
Keep or change the Name, permissions and Expires in.
Select Replace credential.
Copy the new credential from the dialog.

The old credential stops working the moment the replacement is created, and programs still using it get 401 unauthenticated until you give them the new one. Replace during a quiet period, or create a second credential first and switch programs over before revoking the old one.

Revoke a credential

Select Revoke next to the credential. A notice confirms Credential revoked.

Revoking blocks future requests at once.
Revoking also ends the delegated credentials the key handed out, such as those used by hosted turns and sandboxes it started.
Work already in progress is handled separately from the revocation.

If a credential might have leaked, revoke it first, then create a new one.

OAuth for MCP hosts and the CLI

MCP hosts and the CLI sign in through the browser instead of a pasted credential. The authorization server is https://api.wavemaker.io.

Sign-in uses the authorization code flow with PKCE (S256).
Dynamic client registration and client ID metadata documents are supported, so most hosts need no client ID or secret.
The consent page lists each requested permission: View your workspace (read), Generate media (run), Create and edit (write), Publish and share (publish) and Use native agents (agent).
A request must include read, or it is refused invalid_scope. Sign-in also fails when your account doesn't hold a requested scope; reconnect and ask for fewer scopes.
Access tokens last 15 minutes. Hosts and the CLI renew them on their own with a refresh token.
A grant lasts 30 days from sign-in. Renewing doesn't extend it; after 30 days, sign in again.
Each refresh token works once. Presenting a used refresh token again (outside a 30-second retry window) ends the whole grant.
Input-constrained clients can use the device authorization grant at /oauth/device_authorization. The code lasts 10 minutes, and clients poll every 5 seconds.

The CLI has no public release yet. Once it is available, sign in from a terminal:

wavemaker --service https://api.wavemaker.io login
wavemaker --service https://api.wavemaker.io auth status --json

login requests read run write agent; login --publish adds publish. See Native CLI.

Apps you authorized appear in Connections › App grants with their Access, Expires and Status. Select Revoke grant to end one. Revoking a grant takes effect when the Undo notice closes.

A host's own tool-approval prompt is separate from these scopes. Approving a tool call in the host is not a Wavemaker receipt; the job and its charge are recorded by Wavemaker.

Bring your own provider key

You can save your own key for a model provider. That provider's models then run on your key: the provider bills you, and Wavemaker charges no credits for those calls.

Open Connections. The Provider accounts tab opens first.
Select Add connection. It appears only when provider connections are enabled and your session has write access.
Choose a Provider.
Optionally, open Name & sharing to set a Connection name and Who can use this key?: Only me, or Everyone in this workspace (administrators only).
Select Continue to API key. A private enrollment page opens.
Paste the key and select Save & check access (or Save connection for a provider without an access check).

The enrollment link works once and expires after 10 minutes. Keys are entered only on that private page; they never pass through tool arguments, chat, MCP or the API. They are stored encrypted and are never returned to the browser, the agent, job results or errors.

Connection states

Each provider card shows one status:

Status	Meaning
Access verified	The last check reached the provider with this key
Access not checked	The key is saved but has not been checked
Key saved · Not verified	This provider has no access check; it is checked on first use
Access denied	The provider refused this key for the checked access
Key needs attention	The provider reported the key as invalid
Provider is offline	The provider could not be reached
Check unavailable	The check could not run; select Retry
Needs a key	The connection exists but has no saved key
Disconnected	The connection was revoked

Check access asks the provider whether the key works. The check doesn't generate media or spend credits, and you can run it again after five seconds. Replace key opens a new enrollment page. Disconnect revokes the connection.

What a saved provider key pays for

Once a provider has a saved key you can use, every generate call to that provider's routes runs on your key and is charged zero credits. The quote and hold are 0, and the ledger line reads payer: customer with charge byo.
Keys apply to these providers, as the Provider list names them: Alibaba, Anthropic, ElevenLabs, Firecrawl, Gemini, Grok · xAI, Ideogram, Kling, Luma, Minimax (MiniMax), OpenAI, Runway, Seedance, Seedream and Sync. Over the API, connections.create accepts a few other provider ids; a key saved for one of those doesn't fund generate calls.
Your own personal key is used before a workspace key. Among keys of the same kind, the most recently saved one wins. Another member's personal key is never used.
The key is chosen when the work is submitted. A key replaced or revoked after that point refuses the job before anything is sent to the provider, and no credits are charged.
Wavemaker's own GPU models, edit, run, the hosted agent's model, and partner nodes inside graphs are still paid from credits.

When the provider refuses your key

If the provider answers that the key is invalid (401, or a 400 invalid-key reply), not allowed for that model (403), out of credit (402) or rate-limited (429), the job fails with a message and details.connection naming the connection. Wavemaker never retries that call on its own key or your credits. Fix the key with Replace key, or select Disconnect to go back to paying in credits.

Who can manage a connection

A personal connection is visible to and managed by you alone.
Only a workspace administrator can create a workspace connection. Members can then use it, and their usage is billed to that provider account.
The hosted agent's delegated credentials cannot create, enroll, check or revoke connections.
Over the API, connections.create, connections.list, connections.inspect, connections.test, connections.enrollment and connections.revoke are served at POST /api/v1/ops/{name}. connections.enrollment returns the one-use link; the key itself is still entered on the private page.

Security practices

Give each program its own credential with the fewest scopes it needs, and the shortest expiry that fits.
Store credentials in a secret manager or a file only you can read. Never commit them, and never paste one into a prompt, a graph or a support message.
Replace credentials on a schedule, before they expire.
Revoke at once if a credential may have leaked, then check Usage and credits for unexpected work.
Treat a provider key the same way: anyone using a shared workspace connection spends on that provider account.
Wavemaker never asks for a password, recovery code or provider key through the API, MCP or chat.