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


---

# 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.butlr.io/getting-started/mint-client-credentials.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.