# Authentication

The MVMNT API uses **OAuth 2.0** with the **client credentials** grant type for machine-to-machine (M2M) authentication.

## Overview

Authentication follows this flow:

1. You receive **API credentials** (client ID and secret) from MVMNT
2. Exchange credentials for a **Bearer access token** at the token endpoint
3. Include the access token in the `Authorization` header for all API requests
4. **Cache the token** and reuse it until it expires
5. Request a new token when the current one expires



```
┌─────────────┐                                ┌─────────────┐
│   Your      │   1. Request token with        │    MVMNT    │
│   System    │      client credentials        │    OAuth    │
│             │──────────────────────────────▶│   Server    │
│             │   2. Return access token       │             │
│             │◀──────────────────────────────│             │
└─────────────┘                                └─────────────┘
       │
       │  3. Cache token
       │
       ▼
┌─────────────┐                                ┌─────────────┐
│   Cached    │   4. Use token for API         │    MVMNT    │
│   Token     │      requests (1 hour)         │     API     │
│             │──────────────────────────────▶│             │
│             │   5. Return API response       │             │
│             │◀──────────────────────────────│             │
└─────────────┘                                └─────────────┘
       │
       │  6. Token expires
       │
       ▼  (Repeat from step 1)
```

## Obtaining Credentials

Contact your MVMNT account manager to request API access. You'll receive:

- **Client ID**: A public identifier
- **Client Secret**: A confidential secret


### Security Best Practices

🔒 **Keep your secret secure!**

- **Never** commit secrets to version control
- **Never** expose secrets in client-side code or public repositories
- **Store** in environment variables or a secure secret management system (e.g., AWS Secrets Manager, HashiCorp Vault)
- **Rotate** credentials periodically
- **Monitor** for unauthorized access


## Token Endpoint


```
POST https://api.mvmnt.io/oauth2/token
```

### Request

**Headers:**


```http
Content-Type: application/x-www-form-urlencoded
```

**Body Parameters:**


```
grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
```

### Example Request (cURL)


```bash
curl -X POST https://api.mvmnt.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

### Success Response

**Status:** `200 OK`


```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3YjNmOGQ5ZTRjMmExZjVlIiwiaWF0IjoxNzA1MzI2NjAwLCJleHAiOjE3MDUzMzAyMDAsInNjb3BlIjoibXZtbnQtYXBpIn0...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

**Response Fields:**

| Field | Type | Description |
|  --- | --- | --- |
| `access_token` | string | JWT Bearer token to use for API requests |
| `token_type` | string | Always `Bearer` |
| `expires_in` | integer | Token lifetime in seconds (3600 = 1 hour) |


### Error Response

**Status:** `400 Bad Request`


```json
{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}
```

**Common Errors:**

| Error Code | Description | Solution |
|  --- | --- | --- |
| `invalid_client` | Client ID or secret is incorrect | Verify credentials |
| `invalid_grant` | Grant type is not `client_credentials` | Use `grant_type=client_credentials` |
| `unauthorized_client` | Client is not authorized | Contact MVMNT support |


## Using the Access Token

Include the access token in the `Authorization` header for all API requests:


```http
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Example API Request


```bash
curl https://api.mvmnt.io/v1/orders \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Token Expiration & Caching

### Token Lifetime

Access tokens expire after **1 hour** (3600 seconds).

### Best Practices

1. **Cache the token** in memory and reuse it for multiple requests
2. **Track expiration** using the `expires_in` value
3. **Refresh proactively** before expiration (e.g., refresh at 55 minutes)
4. **Handle 401 errors** by requesting a new token and retrying