Authentication and keys

Every API request carries a credential in the Authorization header: an API key for your own org, or an OAuth access token when your app acts for a merchant. The API reference lists both schemes and what each scope allows.

curl https://app.rowcall.ai/v1/me \
  -H "Authorization: Bearer $ROWCALL_API_KEY"

GET /v1/me needs no scope, so it's the quickest check that a key works: it answers with the org the key acts for, its mode and its scopes.

A key is rc_live_ or rc_test_ followed by 32 characters. A request without a working credential is refused as UNAUTHENTICATED; one from a suspended org as ORG_SUSPENDED. See Errors.

Test and live keys

A test key (rc_test_…) runs flows in test mode: RowCall walks the flow without dialling, and your test webhook endpoints and test action URL get the same signed requests. A live key (rc_live_…) places real calls to real phones.

A key only sees its own mode. A test key lists and reads test runs and calls only; a live key never sees them. Test runs never count in results or analytics.

Build everything with a test key first. Switch to a live key only when your webhook and action endpoints work.

Scopes

Give each key only what it needs: runs, flows, contacts, calls and actions. Every endpoint in the API reference names the scope it needs, and the scopes table says what each allows. A request outside the key's scopes is refused as FORBIDDEN.

A typical order system needs runs and contacts. Add calls if it reads transcripts or recordings, and actions if it finishes pending actions.

Making, rolling and revoking keys

1. Make a key

   In Developers → API keys, make a key, pick test or live, name it after the system that uses it (for example "Order service"), and choose its scopes. Owners and admins can do this.

2. Copy it once

   The full key is shown once. RowCall keeps only a hash of it. Store it in your secret manager, never in code or a browser.

3. Roll it when people or systems change

   Rolling gives the key a new secret with the same name, mode and scopes. The old secret stops working at once, so deploy the new one straight away.

4. Revoke what you no longer use

   Each key shows when it was last used. Revoke a key nothing uses any more; it stops working at once.

Platforms with many merchants

A key belongs to one org and acts for that org only. Building an app that many stores connect? Use OAuth instead of API keys: each merchant connects their own RowCall org once, and your app gets tokens for it. See Build an integration.