In this guide you will learn how to authenticate your API requests with short-lived tokens obtained by logging 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.

Prerequisites

1

Set up your HTTP client

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

2

Obtain your credentials

Loccus must provide you with your credentials.

---> userpassword

Procedure

1

Log in using your credentials

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

<--- userpassword

---> token

  • Request

  • Response

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

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

  • Requests requiring authentication

  • Headers
Authorization: Bearer {token}

Validations

1

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.

  • Request

  • Response

  • Method — GET
  • Path — /user