# 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.

{% hint style="danger" %}
Please keep your `client_id` and `client_secret` safe. Malicious actors could use them to make requests on your behalf.
{% endhint %}

## 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:

```sh
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:

```json
{
    "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).

{% hint style="danger" %}
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.
{% endhint %}

### Example token

```json
{
  "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.

{% hint style="info" %}
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.
{% endhint %}

### 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":{}}'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lavanda.app/concepts/auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.