Create an API key and make your first request
The REST API lets your own code read and write the records in your app. You authenticate with an API key that you create in the app. The API needs the Business plan or above.
Create an API key
- Open Tools in the sidebar and choose Data & API.
- Open the API Keys tab.
- Click Create API Key.
- Enter a name that says what the key is for, such as "Website sync".
- Optionally set an expiration date.
- Tick the scopes the key needs. Pick at least one.
- Create the key and copy it straight away. You will not be able to see it again.
Keys start with usk_. Each key belongs to one app. If you have several apps in your workspace, create a key in each app you want to reach.
Who can make keys
Owners and admins can make keys, and can see and revoke every key in the app.
Anyone whose role has API keys switched on under Data & API in Roles & permissions can make keys too. They see and revoke only the keys they made, and a key they make can never do more than they can:
- It can only read and change records and see the tables: Records (Read), Records (Write) and Tables (Read).
- Through the REST API it can't use a table that has access rules for roles. A request to such a table is answered with
403. - It stops working if the person who made it leaves the app, or their role no longer includes API keys.
Owners and admins see these keys marked Member's key on the API Keys tab.
Scopes
A scope is a permission. Give a key only what it needs.
- Records (Read) and Records (Write): read, create, update and delete records.
- Automations (Read) and Automations (Execute via HTTP): list and run automations from your code.
- Webhooks (Read) and Webhooks (Write): manage outgoing webhook subscriptions.
- API Keys (Read) and API Keys (Write): manage keys through the API.
Other scopes cover tables, pages, actions and docs. A request that needs a scope the key does not have is answered with 403 and the message "Missing required scope".
Base URL and authentication
The base URL is:
```
https://unstack.us/api/v1
```
Send your key in the X-API-Key header on every request.
```bash
curl "https://unstack.us/api/v1/custom" \
-H "X-API-Key: usk_your_api_key"
```
This first request lists your tables. Each one has a slug, which is what you use in the URL to read and write its records.
```json
{
"data": [
{ "slug": "customers", "table_name": "customers", "schema": { } }
]
}
```
Keep keys safe
- Use a key only on a server. Never put one in a web page or a mobile app where someone could read it.
- Create a separate key for each system that calls the API, so you can revoke one without breaking the others.
- If a key leaks, click Revoke next to it on the API Keys tab and create a new one. A revoked key stops working immediately.
The API Keys tab shows when each key was last used, which helps you find keys nobody needs any more.
Full reference
The View API documentation link on the API Keys tab opens the full reference. The same reference is in the developer docs, and a machine-readable OpenAPI description is at https://unstack.us/api/v1/openapi.json.