In this guide you will learn how to authenticate your API requests with short-lived tokens obtained by signing in using your credentials. This is a prerequisite for the other guides.

If you are unfamiliar with these concepts, follow their links or read the API reference introduction.

✦ Goal: obtain a short-lived token using your credentials and use it for authentication.



Set up your HTTP client

Use the playground or automatically generate requests from the OpenAPI definition.


Obtain your credentials

Loccus must provide you with your credentials.

---> userpassword



Sign in using your credentials

Sign in using your credentials to create a temporary session and obtain the short-lived token associated with it. See the API reference.

<--- userpassword

---> token

  • Method — POST
  • Path — /auth/credentials
  • Body — application/json
  "handle": "{user}",
  "password": "{password}"

Authenticate with the token

Add the token as a bearer token in the Authorization header. Most API endpoints require you to perform this step to authenticate yourself. See the API reference.

The token will stop authenticating requests at the time indicated in its session.

<--- token

---> ✦ authentication

  • Headers
Authorization: Bearer {token}



Validate your user details

To validate that authentication using your credentials is working, get your user details with the short-lived session token you have obtained. See the API reference.

  • Method — GET
  • Path — /user