Authorization

Authorization is done using JWT tokens (opens in a new tab). Tokens are issued to specific users (either a publisher or admin with a specific ID). They contain a set of capabilities that the token represents.

type Token = {
  tokenId: string,
  issuedTo: string,
  expires: number,
  capabilities: ('admin' | 'publisher' | 'refresh')[]
}

By default, tokens also expire after a week. This means that you must refresh a token for a new one before it expires.

Acquiring a token

Exchanging or refreshing an existing token

POST/v1/auth/exchange

Resource ownerAdmin

Exchange an old token for a new one with a subset of initial capabilities and an updated expiry time. Takes in the old token from the Authorization header.

Input payload:

type InputPayload = {
  "issuedTo": string,
  "capabilities": ('admin' | 'publisher' | 'refresh')[]
}

Ensure that issuedTo is a valid publisher or admin. Create one if the user doesn't have a publisher/admin acount.

Getting the 'root' admin token

To generate the auth token necessary to make the very first admin user, you must use the 'root' admin token. This assumes you have access to the machine on which your instance of Distributed Press runs on. This is usually only the case if you are the administrator which set up the instance.

In the root directory of api.distributed.press, execute npm run make-admin which will print out the token to stdout.

If this is not you, please ask your administrator to issue a token to you.

Revoking a token

DELETE/v1/auth/revoke/:tokenId

Admin

Takes a single path parameter tokenId and revokes that token along with all tokens issued using that token recursively. Note that revoking a non-existent token is a no-op.

Admin Self-hosting Distributed Press