API key or OAuth app?

There are two ways to reach a company's data in Ahlan Hamad. Both call the same endpoints with the same scopes; the difference is who issues the credential and how the data owner says yes.

	API key Live	OAuth app Coming soon
Who it is for	One company's own integration or script, or a single-customer pilot	A product that many companies connect to
Who creates the credential	A user of the customer company, in Integrations → API keys	You, once, in the developer console — then each company approves your app
Secrets copied between companies	Yes — the customer gives you the key	No — the company approves on a consent screen
What the company sees	Key name, scopes, last used; revoke the key	Connected apps: who has access, scopes, last used; one-click revoke
Endpoints and scopes	Every endpoint, the same scopes	Every endpoint, the same scopes
Available	Now	Coming soon

Use an API key when

You are integrating your own company (an internal script, or a sync with your accounting system).
You work with one customer, or a handful, in a pilot.
You want to start today: keys and sandbox companies are live now.

A key belongs to one company, carries a fixed set of scopes and is shown once when created. A user with the integrations.manage permission (CEO or HR admin by default) creates it. ah_test_ keys are for sandbox companies, ah_live_ keys for real ones. See the quickstart.

Build an OAuth app when

Coming soon. OAuth apps are being built and are not available yet. What follows describes the planned design; details may change before launch. Start today with an API key on a sandbox — when OAuth ships only your authentication code changes, not the endpoints.

Your product (POS, accounting, banking or an HR tool) will connect to many companies.
You don't want every customer copying a secret key and sending it to you.
You want customers to see your app by name and logo, and revoke it themselves.

How it will work

You create a developer organisation (separate from any customer company) and an app in it: a client ID and secret (shown once, stored hashed, rotatable), exact redirect URIs, the scopes you request, and an English and Arabic listing.
While your app is in development mode it can connect only to sandbox companies your organisation owns. Connecting real companies needs the app to be published after review, or an explicit allow-list entry for a pilot customer.
You send the customer's user to /oauth/authorize. A user with integrations.manage picks the company, sees your app and its scopes, and approves.
You exchange the authorization code for an access token and a refresh token at /oauth/token (authorization code with PKCE S256). Refresh tokens rotate on every use.
You call /v1 with Authorization: Bearer <token> — the same endpoints, the same scope checks, the same rate limit.
The customer sees your app on its Connected apps page and can revoke it in one click; revoking stops your tokens and disables that connection's webhooks.

The technical detail is in the OAuth guide (preview).

Moving from API keys to OAuth

Endpoints, scopes, data shapes and webhooks are the same either way. If you start on API keys, moving to OAuth means changing only how you obtain the Bearer token. API keys stay supported for private, single-company integrations.