Skip to content
/
Authentication
Last updated

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:

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)

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

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

Response Fields:

FieldTypeDescription
access_tokenstringJWT Bearer token to use for API requests
token_typestringAlways Bearer
expires_inintegerToken lifetime in seconds (3600 = 1 hour)

Error Response

Status: 400 Bad Request

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

Common Errors:

Error CodeDescriptionSolution
invalid_clientClient ID or secret is incorrectVerify credentials
invalid_grantGrant type is not client_credentialsUse grant_type=client_credentials
unauthorized_clientClient is not authorizedContact MVMNT support

Using the Access Token

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

Authorization: Bearer YOUR_ACCESS_TOKEN

Example API Request

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
Previous page
Next page