# API Key Management

## List API Keys for your User

### Example cURL Request

```sh
curl --request GET 'https://${BASE_URL}/api/api-keys' \
--header 'Authorization: Bearer ${API_KEY}'
```

### Endpoint Specification

## Get your user

<mark style="color:blue;">`GET`</mark> `/api/api-keys`

Get all of the API keys for your user

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | `Bearer ${API_KEY}` |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "api_keys": [
        {
            "id": "00n06yx75dzuxz2lgi",
            "name": "default api key",
            "created_at": "2023-06-09T06:34:37.685Z",
            "is_active": true
        }
    ]
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    api_keys: Array<{
        id: string
        name: string
        created_at: string
        is_active: boolean
    }>
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Your API key is unrecognized or inactive" %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Server error An unexpected error has occurred on the server." %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 500,
    "message": "Internal server error"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Create an API Key

{% hint style="info" %}
You are allowed to have 2 active API keys per user at any one time
{% endhint %}

### Example cURL Request

```sh
curl --request POST 'https://${BASE_URL}/api/api-keys' \
--header 'Authorization: Bearer ${API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "new api key",
    "deactivate_current": false
}'
```

### Endpoint Specification

## Create a new API key

<mark style="color:green;">`POST`</mark> `/api/api-keys`

Create a new API key and optionally deactivate the API key used to authenticate this request

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | `Bearer ${API_KEY}` |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json    |

#### Request Body

| Name                                                  | Type    | Description                                                                         |
| ----------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>                | string  | The name associated with the new API key.                                           |
| deactivate\_current<mark style="color:red;">\*</mark> | boolean | Set to true if you wish to deactivate the key you use to authenticate this request. |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "api_key": "18077981128785C05993E9C685FD52410BADCD994B3C1D0365A0C7088BA5BAC1"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    api_key: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Your API key is unrecognized or inactive" %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403:  User does not have `API User` role." %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "error": "Forbidden",
    "message": "Permission denied according to assigned roles.",
    "statusCode": 403
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
    error: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="422: Unprocessable Entity There was a problem processing the request" %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 422,
    "timestamp": "2023-06-11T09:23:27.078Z",
    "url": "/api/api-keys",
    "error": "MAX_KEYS_REACHED",
    "message": "You have reached the maximum active API keys for your user. Maximum: 2"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    timestamp: string
    url: string
    error: string
    message: string | string[]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Server error An unexpected error has occurred on the server." %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 500,
    "message": "Internal server error"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

#### 422: Unprocessable Entity `error` types

<table><thead><tr><th width="200">Value from API</th><th>Description</th></tr></thead><tbody><tr><td><code>MAX_KEYS_REACHED</code></td><td>You have reached the maximum active API keys for your user. Maximum: 2</td></tr></tbody></table>

## Deactivate an API Key

{% hint style="info" %}
It is possible to deactivate the key you use to authenticate the request to deactivate. This is for security purposes should your key be compromised. Be aware that if you deactivate your last key you will need to contact [support@thallo.io](mailto:support@thallo.io?subject=Thallo%20API%20New%20API%20Key%20Request) to request a new one.
{% endhint %}

### Example cURL Request

```sh
curl --request DELETE 'https://${BASE_URL}/api/api-keys/${API_KEY_ID}' \
--header 'Authorization: Bearer ${API_KEY}'
```

### Endpoint Specification

## Deactivate an API key

<mark style="color:red;">`DELETE`</mark> `/api/api-keys/${API_KEY_ID}`

Deactivate an API key by its id

#### Path Parameters

| Name                                           | Type   | Description                                         |
| ---------------------------------------------- | ------ | --------------------------------------------------- |
| API\_KEY\_ID<mark style="color:red;">\*</mark> | string | The id of the API key you would like to deactivate. |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | `Bearer ${API_KEY}` |

{% tabs %}
{% tab title="200: OK There is no body returned from this endpoint" %}

{% endtab %}

{% tab title="401: Unauthorized Your API key is unrecognized or inactive" %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="422: Unprocessable Entity There was a problem processing the request" %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 422,
    "timestamp": "2023-06-11T09:23:27.078Z",
    "url": "/api/api-keys",
    "error": "API_KEY_NOT_EXISTS",
    "message": "Api key not found"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    timestamp: string
    url: string
    error: string
    message: string | string[]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Server error An unexpected error has occurred on the server." %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 500,
    "message": "Internal server error"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

#### 422: Unprocessable Entity `error` types

<table><thead><tr><th width="200">Value from API</th><th>Description</th></tr></thead><tbody><tr><td><code>API_KEY_NOT_EXISTS</code></td><td>Api key not found</td></tr></tbody></table>