🔐 Authentication

Machine-to-machine authentication made simple

The Bottom Line

We use OAuth 2.0 Client Credentials Flow - the standard for server-to-server authentication. No user logins, no redirects, just clean API-to-API communication.

🎯 Keep it Simple: Your scopes are pre-configured when you receive your credentials - just authenticate and go!

Why Client Credentials?

Your integration is a confidential client - a server application that can safely store secrets. Unlike user-facing apps, you don't need to worry about:

🚫 Browser redirects
🚫 User consent screens
🚫 Authorization codes
🚫 Callback URLs

You get:

✅ Direct token exchange
✅ Simple credential management
✅ Perfect for automation
✅ Short-lived tokens (5 minutes) for enhanced security

Token Flow

sequenceDiagram
    participant Client as Your Application
    participant Auth as Identity Provider
    participant API as LIKE MAGIC Open API

    Client->>Auth: POST /token<br/>(client_id + client_secret)
    Auth->>Auth: Validate credentials
    Auth-->>Client: Access Token (JWT)<br/>expires_in: 300s
    Client->>API: API Request<br/>Authorization: Bearer {token}
    API->>API: Validate token
    API-->>Client: 200 OK (Response data)

The Tokens Explained

Access Token (JWT)

Purpose: Your API passport 🎫
Lifetime: 5 minutes (300 seconds)
Format: JSON Web Token (JWT)
Usage: Send with every API request as Authorization: Bearer {token}
Security: If compromised, expires automatically in 5 minutes

Refresh Token

We don't use them - Client credentials flow doesn't need refresh tokens. Just request a new access token when yours expires. Simple!

Token Endpoint

{{tokenEndpoint}}

Get Your Client Credentials

Client credentials (clientId and clientSecret) are obtained by creating a service account. Service accounts are managed by your LIKE MAGIC Account Admin through the Operational Platform.

👉 See the Manage Service Accounts Guide for detailed instructions on creating service accounts and obtaining your credentials.

Get Your Token

We support two ways to authenticate - pick whichever fits your stack better!

Method 1: Credentials in Body

Simple and explicit - send credentials as form parameters.

curl --location '{{tokenEndpoint}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET'

Method 2: Basic Authentication

Cleaner body, credentials in header - great for HTTP client libraries.

curl --location '{{tokenEndpoint}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic BASE64(client_id:client_secret)' \
  --data-urlencode 'grant_type=client_credentials'

Response (Both Methods)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "guest_conversation.write event_log.read"
}

Use Your Token

API Request

curl --location '{{monitoringUrl}}/api/...' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

Scopes - Pre-Configured Per Client

Scopes are fixed to your client ID - no need to request them! When you receive your credentials, they come pre-configured with the scopes you need.

Your token response will show which scopes are assigned:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "guest_conversation.write event_log.read"  // ← Your pre-configured scopes
}

Authentication Method Comparison

Method	Pros	Cons	Best For
Body Parameters	✅ Explicit and visible ✅ Easy to debug ✅ Works everywhere	❌ Credentials in body	Quick testing, simple scripts
Basic Auth	✅ Standard HTTP auth ✅ Cleaner request body ✅ Built into most HTTP libs	❌ Requires base64 encoding	Production apps, HTTP libraries

Both methods are equally secure over HTTPS and produce identical results. Choose based on your preference!

Best Practices

✅ DO

Cache tokens and reuse until expiration - With 5-minute tokens, this is critical!
Implement automatic token refresh on 401 responses
Store credentials securely (env vars, secret managers)
Use HTTPS for all requests
Monitor token expiration time and refresh proactively (e.g., 30 seconds before expiry)
Check the scope field in token response to verify your permissions

❌ DON'T

Request new tokens for every API call (you'll hit rate limits!)
Store credentials in code or version control
Share credentials across environments
Ignore 401 responses - they mean "get a new token"
Try to request custom scopes - they're fixed per client

💡 Pro Tip: With 5-minute tokens, implement smart caching that refreshes tokens proactively before they expire. This prevents 401 errors during critical operations.

Troubleshooting

Issue	Cause	Solution
`401 Unauthorized`	Token expired or invalid	Request a new token
`401 Unauthorized` (token endpoint)	Invalid Basic Auth encoding	Verify base64 encoding of `client_id:client_secret`
`403 Forbidden`	Client lacks required scope	Contact your integration manager - scopes are pre-configured per client
`400 Bad Request` (token endpoint)	Invalid credentials	Verify client_id and client_secret
`invalid_client` error	Client ID not found or disabled	Verify client_id is correct and active

Testing Basic Auth encoding:

# Verify your Basic Auth header
echo -n "your_client_id:your_client_secret" | base64
# Should match what you're sending in Authorization header

🛡️ Security Reminders

Credentials are keys to the kingdom - Treat client_secret like a password
Tokens are temporary keys - They expire for a reason
HTTPS everywhere - Never send credentials over HTTP
Scopes are pre-configured - Your client has exactly the permissions it needs, no more, no less
Rotate credentials regularly - Especially if you suspect exposure

Ready to authenticate? Get your credentials from your LIKE MAGIC admin! 🚀

Read the 🔑 Manage Service Accounts Guide