Auth

Lavanda's platform boasts a variety of authentication and authorization systems tailored to specific use cases. This document focuses on the intricacies of third-party API integrations.

Getting started

In order to connect to our API you will need to obtain a client_id and client_secret.

Please reach out to our customer success team to procure these details.

Please keep your client_id and client_secret safe. Malicious actors could use them to make requests on your behalf.

Obtaining a token

To interact with the API, clients must provide a token as an Authorization header in each request. These tokens follow the JWT (JSON Web Token) standard and can be acquired with the aforementioned client_id and client_secret.

You can make a POST request to our API with a grant_type and your credentials to obtain a token.

https://platapi.lavanda.app/v1/oauth2/token

Here is an example cURL request:

curl --location 'https://platapi.lavanda.app/v1/oauth2/token' \
--header 'Content-Type: application/json' \
--data '{
    "grant_type": "client_credentials",
    "client_id": “xxx”,
    "client_secret": “xxx”
}'

Assuming the request is a success, you will receive a response in the following format:

{
    "access_token": "xxx",
    "expires_in": 3600,
    "token_type": "Bearer"
}

• access_token - The token you can use to make requests

• expires_in - The length of time the token is valid for (once it expires you will need to generate a new one)

Once you have received your token, you can use the introspection tool on https://jwt.io/ to view the internals. (Lavanda is not responsible for the content of external sites).

Please remember to keep your token safe. Even though it has an expiry date, malicious actors could use it to make requests on your behalf.

Example token

{
  "sub": "xxx",
  "token_use": "access",
  "scope": "platapi/lavanda",
  "auth_time": 1723021787,
  "iss": "https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_xxxxxxxxx",
  "exp": 1723025387,
  "iat": 1723021787,
  "version": 2,
  "jti": "2c01fe59-64fc-45e5-9e30-54856d022b95",
  "client_id": "xxx"
}

• sub - Subject (this is the unique id of the person requesting the token)

• iss - Issuer (this is the service which issues the token - in our case this is AWS Cognito)

• exp - Expiry date

• iat - Issued at

• client_id - Client id (same value as the subject)

Token refresh

When a token expires it will become invalid and you will need to generate a new one. To do so, you can follow the same process above.

Since each token is generated independently it is possible to have multiple at once. For security reasons we recommend you reuse a token until it's expiry instead of creating a new one for each request.

Scopes

Although the example token above contains a scope, at Lavanda we don't pass scopes on a per operation level in the token. Due to the fine-grained access control nature of our API we use operation based scopes internally to determine whether a client has permissions to perform all or part of a request.

Accessing your data

Assuming you have acquired a valid token you should now be able to make requests to our API. Since our tokens work across workspaces it is possible to finely tune what access a given token has. Please reach out to our customer support team for more information.

Making a request

Once you have your token you can include it as an Authorization header as follows, adjust the query to suit your needs:

curl --request POST \
    --header 'content-type: application/json' \
    --header 'Authorization: Bearer xxx' \
    --url 'https://platapi.lavanda.app/v1' \
    --data '{"query":"","variables":{}}'