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.
Here is an example cURL request:
Assuming the request is a success, you will receive a response in the following format:
access_token
- The token you can use to make requestsexpires_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
- 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 dateiat
- Issued atclient_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.
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:
Last updated