Authentication

How to authenticate your API requests with API keys.

API Keys

The eWasl API uses API keys to authenticate requests. Each key is scoped with specific permissions and can be revoked independently.

API keys follow the format ewasl_ followed by a random string. They are only shown once at creation time — store them securely.

Generating an API Key

1. Log in to your eWasl account.
2. Navigate to Settings > API Keys.
3. Click Create New Key.
4. Give your key a descriptive name (e.g., "Production App", "CI Pipeline", "MCP Integration").
5. Select the permissions your key needs (posts:read, posts:create).
6. Copy the generated key immediately — it will not be shown again.

You can also create keys programmatically via the Create Key endpoint.

Using the API Key

Include the API key in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer ewasl_YOUR_API_KEY

Example: List Posts

curl https://app.ewasl.com/api/v1/posts \
  -H "Authorization: Bearer ewasl_abc123def456..."

Example: Create a Post

curl -X POST https://app.ewasl.com/api/v1/posts \
  -H "Authorization: Bearer ewasl_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from the eWasl API!",
    "accountIds": ["your-account-uuid"],
    "publishNow": true
  }'

Permissions

Each API key is scoped to specific permissions. Only the operations covered by the key's permissions will succeed.

| Permission | Description | Required For | | :--- | :--- | :--- | | posts:read | Read post data | GET /api/v1/posts, GET /api/v1/connections | | posts:create | Create and publish posts | POST /api/v1/posts, POST /api/v1/posts/schedule |

If a key lacks the required permission, the API returns a 403 Forbidden error:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required permission: posts:create"
  }
}

Error Responses

| HTTP Status | Error Code | Meaning | | :--- | :--- | :--- | | 401 | UNAUTHORIZED | No API key provided, or key is invalid/expired | | 403 | FORBIDDEN | Key is valid but lacks the required permission | | 429 | RATE_LIMITED | Too many requests — wait and retry |

401 Response Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Valid API key required. Include Authorization: Bearer ewasl_... header."
  }
}

Security Best Practices

• Keep keys secret — Never commit API keys to source control or expose them in client-side JavaScript. Use environment variables.
• Use least privilege — Only grant the permissions your application actually needs.
• Rotate keys regularly — Revoke old keys and create new ones periodically, especially after team member changes.
• Use separate keys — Create different keys for different environments (development, staging, production) and different applications.
• Monitor usage — Check the last_used_at timestamp on your keys in the dashboard to detect unauthorized use.
• Revoke compromised keys — If a key is leaked, revoke it immediately via the dashboard or the Revoke Key endpoint.