Skip to main content

​
Authentication

NativeMessage supports two authentication methods: JWT Bearer tokens for user-based access and API keys for server-to-server integrations.

​
JWT Bearer Token

JWT authentication provides short-lived access tokens with automatic refresh capabilities. Best for applications requiring user-level permissions.

​
Login Flow

Obtain an access token by providing username and password: 
curl -X POST https://api-message.nativehub.live/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900
}

​
Using Access Tokens

Include the access token in the Authorization header: 
curl https://api-message.nativehub.live/api/v1/messages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Token Refresh

Access tokens expire after 15 minutes. Use the refresh token to obtain a new access token: 
curl -X POST https://api-message.nativehub.live/api/v1/auth/refresh \
  -H "Authorization: Bearer REFRESH_TOKEN"

​
Token Lifecycle

  • Access Token: Valid for 15 minutes
  • Refresh Token: Valid for 7 days
  • Refresh tokens can be used multiple times until expiration

​
API Key Authentication

API keys provide persistent authentication for server-to-server integrations without token management overhead.

​
Creating an API Key

  1. Log in to the NativeMessage dashboard
  2. Navigate to Settings → API Keys
  3. Click “Generate New Key”
  4. Copy and securely store the key (shown only once)

​
Using API Keys

Include the API key in the X-API-Key header: 
curl https://api-message.nativehub.live/api/v1/messages \
  -H "X-API-Key: nmk_live_1234567890abcdef"
API keys inherit the permissions of the user who created them and remain valid until explicitly revoked.

​
Rate Limiting

All API requests are subject to rate limits of 200 requests per minute per tenant.

​
Rate Limit Headers

Each response includes rate limit information: 
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1676543210
  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Unix timestamp when the limit resets
Exceeding rate limits returns a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

​
Best Practices

Secure Storage

Store tokens and API keys in environment variables or secure vaults, never in source code

Token Refresh

Refresh JWT access tokens proactively before expiration to avoid interruptions

Server-to-Server

Use API keys for automated systems and background processes

Key Rotation

Rotate API keys periodically and revoke unused keys immediately