Authenticate & verify

Every v2 request authenticates with an API key sent as a Bearer token. This takes about two minutes.

1. Create a key

In the Sortd app, go to Settings → API and create a key. Choose the scopes it needs (e.g. tasks.read, tasks.write). The secret — sk_live_… — is shown once, so copy it immediately and store it somewhere safe.

Keys are team keys: they act for the team you created them in, and the owner must have access to that team plus an active subscription.

2. Send it as a Bearer token

GET /me needs no scopes, so it's the quickest way to confirm a key works. Send the key in the Authorization header (the header name is Authorization; the value is the word Bearer, a space, then the key).

# curl
curl "https://api.sortd.com/v2/me" \
  -H "Authorization: Bearer sk_live_…"

// JavaScript (fetch)
const res = await fetch("https://api.sortd.com/v2/me", {
  headers: { Authorization: "Bearer sk_live_…" },
});
const { data } = await res.json();
console.log(data.user_id, data.key.scopes);

// C# (HttpClient)
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "sk_live_…");
var res = await client.GetAsync("https://api.sortd.com/v2/me");
var json = await res.Content.ReadAsStringAsync();

# Python (requests)
import requests
res = requests.get(
    "https://api.sortd.com/v2/me",
    headers={"Authorization": "Bearer sk_live_…"},
)
print(res.json()["data"])

3. Read the response

A 200 confirms the key. Every response is { data, meta }:

{
  "data": {
    "user_id": "…",
    "email": "you@example.com",
    "display_name": "You",
    "key": { "id": "key_…", "type": "team", "scopes": ["tasks.read", "tasks.write"] }
  },
  "meta": { "request_id": "req_…" }
}

Troubleshooting

• 401 / token invalid — the key wasn't sent as a Bearer token. In the reference's "Try It", pick the Bearer scheme and paste only the sk_… value (don't type the word Bearer). Using a raw header, it must be Authorization: Bearer sk_live_… — a header literally named Bearer won't work.
• not authorized on resource endpoints — /me works but /boards or /tasks return an authorization error: the key owner's team needs an active subscription, and you must request a team/board/list the owner has access to. Use ids from your own /me and /teams responses.
• 403 scope_insufficient — the key is missing a scope the endpoint requires. Re-create it with the needed scopes (each endpoint lists them in the reference).

Next: create a task.