Authentication

Every request to Numbers, Emails and Captchas is authenticated with your project’s API key, sent in the X-API-Key header.

curl https://api.clearance.rest/numbers/list \
  -H "X-API-Key: cr_live_..."

A missing or invalid key returns 401.

Your key

• Keys start with cr_live_.
• Each project has one key. It is shown on the project page in the console, where you can also rotate it.
• The key identifies the project, so it also decides which numbers and mailboxes a request can see. Two projects never see each other’s numbers.
• The project’s id is not a key and is never accepted as one.

Keep the key on your server. Do not ship it in a browser or mobile app.

Clients that cannot send headers

If a client cannot set custom headers (for example a link that is opened directly), pass the key as the api_key query parameter instead:

https://api.clearance.rest/emails/attachments/1783459025000_1_invoice.pdf?api_key=cr_live_...

Prefer the header wherever you can: query strings end up in logs.

Endpoints that do not take the API key

A few endpoints are called by other systems, or by a browser, and identify the caller some other way. You do not need your API key for them:

• Claim socket (GET /numbers/providers/mobile/claim/socket) takes a single-use ticket instead. A browser WebSocket cannot send headers and your key must not reach the browser, so your backend exchanges the key for a 60-second ticket with POST /numbers/providers/mobile/claim/ticket. See Mobile numbers.
• SIM Bridge download (GET /numbers/providers/mobile/download_apk) is open, so a phone with nothing installed can fetch the app.

Rotating a key

Rotating a key in the console invalidates the old one. The change reaches every service within about 30 seconds, so update the clients that use the key promptly.

SDKs

The Node.js and PHP SDKs read the key from the CLEARANCE_REST_API_KEY environment variable and send the header for you.