Mint Client Credentials

Client Credential Credential Grant via Butlr API

OAuth 2.0 Client Credentials Grant Type.

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

Authorization: Bearer your-jwt-token

---

Endpoints

Create M2M Client

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

Request:

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

Request Body:

{
    "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):

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

Example cURL Command:

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:

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

Response (200 OK):

[
    {
        "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:

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

---

Get M2M Client

Retrieves a specific M2M client by ID.

Request:

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

Response (200 OK):

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

Example cURL Command:

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

---

Delete M2M Client

Deletes a specific M2M client.

Request:

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

Response (204 No Content)

Example cURL Command:

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:

{
    "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:

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

OR

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

---

404 Not Found

Occurs when the requested client is not found.

Example Response:

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

---

500 Internal Server Error

Occurs when an unexpected error happens.

Example Response:

{
    "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