Authentication

In order to access protected endpoints, you'll need an access token which contains data on your user identity and permissions. Our client packages handle authentication automatically, so we strongly recommend using those if you can.

Registration

Registration currently requires raw POST requests as we don't have any UI built for it yet. In the future, registered users will be limited to actual user accounts.

POST
/register

Payload

      {
  user_id: <username>,
  user_secret: <password>
}

    

Response

      {
  user_key: <key>
}

    

The user_key and user_secret is what you'll need to get your access/refresh token, so make sure to save them somewhere safe.

Getting the access token

The access token is like a passport. It tells us who you are and what you're allowed access. And just like a real passport, they expire way too quickly. For us, this means they expire within 1 hour. Don't worry though, you'll also be given a long-lived refresh_token on your first authentication request.

This setup helps us mitigate the risk of an attacker abusing leaked access tokens when accessing resource servers.

POST
/authenticate

Payload

      {
  user_key: <key>,
  user_secret: <password>,
}

    

Response

      {
  access_token: <access_token>,
  refresh_token: <refresh_token>
}

    

Refreshing your access token

If you've read everything before (I salute you sir, if you did), you'll know that access tokens expire within 1 hour. To refresh them, we urge you to use the /refresh endpoint instead of authenticating directly again. If the refresh token leaks, we can easily change it, but if your user credentials leak, you might also have trouble on other services where you use the same password.

POST
/refresh

Payload

      {
 refresh_token: <refresh_token>
}

    

Response

      {
 access_token: <access_token>
}

    

Further documentation

For detailed docs, including some fancy visualized model, check out the official Github repo.

loading

Connected!