Get started

Authentication

The Platform API authenticates with a service token. Send it as a bearer token in the Authorization header of every request.

Send the token

A service token starts with ptk_. Each token belongs to exactly one organization (a tenant), and that organization is the only one a request made with it can reach. A member that belongs to another organization is answered exactly like a member that does not exist: 404.

curl http://localhost:8000/v1/members/PA-0001/changes \
  -H "Authorization: Bearer ptk_sandbox_meridian_demo"

import requests

r = requests.get(
    "http://localhost:8000/v1/members/PA-0001/changes",
    headers={"Authorization": "Bearer ptk_sandbox_meridian_demo"},
)
print(r.status_code)

const r = await fetch("http://localhost:8000/v1/members/PA-0001/changes", {
  headers: { Authorization: "Bearer ptk_sandbox_meridian_demo" },
});
console.log(r.status);

Get a token

An administrator of your organization creates tokens in Arc Watch, under Settings, then Integrations, then Create key. Each key has a name you choose. The full key is shown once, when it is created; afterwards only its first characters are shown, so copy it then and keep it secret. Keys can be revoked from the same screen, and the list shows when each was last used.

The same thing is available as a call, made by a signed-in administrator (not with a service token):

Protearc stores only a hash of each token, so a lost token cannot be shown again: create a new one and revoke the old.

curl -X POST http://localhost:8000/v1/settings/api-keys \
  -H "Authorization: Bearer <administrator sign-in token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Billing"}'

import requests

r = requests.post(
    "http://localhost:8000/v1/settings/api-keys",
    headers={"Authorization": "Bearer <administrator sign-in token>"},
    json={"name": "Billing"},
)
print(r.json()["key"])  # shown only in this response

const r = await fetch("http://localhost:8000/v1/settings/api-keys", {
  method: "POST",
  headers: {
    Authorization: "Bearer <administrator sign-in token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Billing" }),
});
console.log((await r.json()).key); // shown only in this response

When the token is wrong

A missing, malformed, unknown or revoked token is answered with 401, the header WWW-Authenticate: Bearer, and the same body in every case, so the response does not reveal why.

Service tokens work on the platform routes only. Routes for people signed in to Arc Watch take a sign-in token instead, and a service token is refused there.

json Response 401

{ "detail": "invalid token" }