# Mint Client Credentials

[OAuth 2.0 Client Credentials Grant Type](https://oauth.net/2/grant-types/client-credentials/).

* The client credentials grant type is ideal when an application needs to authenticate itself to access its own resources or perform operations that are not user-specific. Commonly used in server-to-server interactions, this method allows the application to act autonomously by obtaining an access token using only its client ID and secret, without involving any end-user.

***

## Auth0 M2M Client Service

### Overview

The **Auth0 M2M Client Service** manages Machine-to-Machine (M2M) clients. All endpoints require a valid JWT token with a `client_id`.

### Authentication

All requests must include a valid JWT token in the `Authorization` header:

```http
Authorization: Bearer your-jwt-token
```

***

### Endpoints

#### Create M2M Client

Creates a new Machine-to-Machine client in Auth0.

**Request:**

```http
POST /api/v1/client
Content-Type: application/json
Authorization: Bearer your-jwt-token
```

**Request Body:**

```json
{
    "name": "My API Client",
    "description": "Client for accessing internal APIs"
}
```

**Behavior:**

* The client is automatically associated with the `client_id` from your JWT token.
* It is authorized for the Butlr API (`https://butlrauth/`) with the following scopes:
  * `read:spaces`, `write:spaces`, `delete:spaces`
  * `read:rooms`, `write:rooms`, `delete:rooms`
  * `read:sensors`, `write:sensors`, `delete:sensors`
  * `read:hives`, `write:hives`, `delete:hives`

**Response (201 Created):**

```json
{
    "name": "My API Client",
    "description": "Client for accessing internal APIs",
    "client_id": "client_{ksuid}",
    "client_secret": "your-client-secret-here"
}
```

**Example cURL Command:**

```bash
curl -X POST http://localhost:4010/api/v1/client \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Client",
    "description": "Client for accessing internal APIs"
  }'
```

***

#### List M2M Clients

Retrieves all M2M clients.

**Request:**

```http
GET /api/v1/client
Authorization: Bearer your-jwt-token
```

**Response (200 OK):**

```json
[
    {
        "id": "abc123def456",
        "name": "My API Client",
        "description": "Client for accessing internal APIs",
        "client_id": "abc123def456"
    },
    {
        "id": "xyz789",
        "name": "Another Client",
        "description": "Secondary API client",
        "client_id": "xyz789"
    }
]
```

**Example cURL Command:**

```bash
curl http://localhost:4010/api/v1/client \
  -H "Authorization: Bearer your-jwt-token"
```

***

#### Get M2M Client

Retrieves a specific M2M client by ID.

**Request:**

```http
GET /api/v1/client/{id}
Authorization: Bearer your-jwt-token
```

**Response (200 OK):**

```json
{
    "id": "abc123def456",
    "name": "My API Client",
    "description": "Client for accessing internal APIs",
    "client_id": "abc123def456"
}
```

**Example cURL Command:**

```bash
curl http://localhost:4010/api/v1/client/abc123def456 \
  -H "Authorization: Bearer your-jwt-token"
```

***

#### Delete M2M Client

Deletes a specific M2M client.

**Request:**

```http
DELETE /api/v1/client/{id}
Authorization: Bearer your-jwt-token
```

**Response (204 No Content)**

**Example cURL Command:**

```bash
curl -X DELETE http://localhost:4010/api/v1/client/abc123def456 \
  -H "Authorization: Bearer your-jwt-token"
```

***

### Error Responses

#### `400 Bad Request`

Occurs when the request is invalid.

**Example Response:**

```json
{
    "code": "INVALID_REQUEST",
    "message": "client name is required"
}
```

***

#### `401 Unauthorized`

Occurs when the JWT token is missing, invalid, or missing a `client_id`.

**Example Responses:**

```json
{
    "message": "missing or malformed jwt"
}
```

OR

```json
{
    "message": "token is valid but missing client_id"
}
```

***

#### `404 Not Found`

Occurs when the requested client is not found.

**Example Response:**

```json
{
    "code": "CLIENT_NOT_FOUND",
    "message": "client not found"
}
```

***

#### `500 Internal Server Error`

Occurs when an unexpected error happens.

**Example Response:**

```json
{
    "message": "Internal server error"
}
```

***

### Error Codes

| Code                         | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `INVALID_REQUEST`            | The request is missing required fields or contains invalid data |
| `CLIENT_NOT_FOUND`           | The requested client does not exist                             |
| `CLIENT_CREATE_FAILED`       | Failed to create the client                                     |
| `CLIENT_GRANT_CREATE_FAILED` | Failed to authorize client for API access                       |
| `CLIENT_UPDATE_FAILED`       | Failed to update the client                                     |
| `CLIENT_DELETE_FAILED`       | Failed to delete the client                                     |