Authenticating

The Shapecaster API has two levels of authentication. Every request carries an authorization token — either your private administrator token or a private user session token — and which one you send depends on the endpoint.

The administrator tier

That's you, the account holder, talking to the API directly. An administrator token is accepted on every endpoint — it creates user tags, mints sessions for your users, manages frames, and reads across all your users' records rather than one user's at a time. It can also act on a user's behalf, which is what naming a user_tag does.

The user tier

Your users are the people in your client apps. They never talk to the API themselves and need no concept of it — your app authenticates each one by minting a session with your administrator token and then sending the resulting session token in place of it. A session token is bound to a single user tag, so it only ever acts as that user.

Authentication token strings

Either kind of token is a UUID behind a prefix naming its tier — adtk_ for an administrator token, ustk_ for a user session token. The prefix is part of the token, so send the whole string. See token values in the Reference for the format and an example of each.

Which token an endpoint needs

Every endpoint on every resource page carries a chip naming the token it needs. That chip names the minimum — an administrator token is accepted everywhere, including on the endpoints marked as needing a user token. In the other direction, a user token on an endpoint marked administrator is refused with a 403 Forbidden.

With an admin token, name the user

Some things belong to a particular user. A session token says who that is by itself, since it is bound to one user tag. An administrator token isn't bound to anyone, so when the action needs an owner you name one with a user_tag parameter:

• Creating a table, a table link, or a table document as an administrator means passing user_tag to name the owner. Sent with a user session token, user_tag is ignored — the session's own tag owns what it creates.
• The tag you name has to be one of your own user tags. Naming a tag belonging to another client's account gets you a validation error, not another account's data.
• Modifying or deleting a table works by its id, and a user_tag you name alongside must be that table's owner — you can't act on one owner's table while naming another.
• Reading needs none of this. Reads aren't owner-scoped, so listing, searching, and fetching return every owner's records regardless of which token you used.

Sending your token

Attach your token to every request as a Bearer token in the Authorization header. Here is an administrator token on a read — listing frames:

curl

curl -i "https://api.cxipgroup.com/frames" \
  -H "Authorization: Bearer adtk_c1f4e2a7-9b3d-4e6a-8f21-0a5c7d9e1b34"

JavaScript

const response = await fetch("https://api.cxipgroup.com/frames", {
  method: "GET",
  headers: {
    "Content-type": "application/json; charset=UTF-8",
    "Authorization": "Bearer adtk_c1f4e2a7-9b3d-4e6a-8f21-0a5c7d9e1b34"
  },
});

A request that carries a body adds Content-Type and nothing else. Minting a session, which is how a ustk_ token comes to exist in the first place:

curl

curl -i "https://api.cxipgroup.com/sessions" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer adtk_c1f4e2a7-9b3d-4e6a-8f21-0a5c7d9e1b34" \
  -d '{ "user_tag": "a9f201c2-36eb-41e1-b30a-7bd180f02e91" }'

JavaScript

const response = await fetch("https://api.cxipgroup.com/sessions", {
  method: "POST",
  body: JSON.stringify({
    user_tag: "a9f201c2-36eb-41e1-b30a-7bd180f02e91"
  }),
  headers: {
    "Content-type": "application/json; charset=UTF-8",
    "Authorization": "Bearer adtk_c1f4e2a7-9b3d-4e6a-8f21-0a5c7d9e1b34"
  },
});

PUT and DELETE go the same way — the header doesn't change with the method. A user session token sits in exactly the same place, with ustk_ where the adtk_ is.