Authentication

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
  }'

Selecting a Workspace

Post endpoints default to the API credential owner's personal workspace. To act inside a shared workspace, include its UUID in x-ewasl-workspace-id:

curl https://app.ewasl.com/api/v1/posts \
  -H "Authorization: Bearer ewasl_abc123def456..." \
  -H "x-ewasl-workspace-id: 11111111-1111-4111-8111-111111111111"

The header never grants access. eWasl verifies current membership, workspace availability, role permissions, assigned brands, and the workspace owner's entitlement on every request. A malformed identifier returns 400; revoked or insufficient access returns 403. Never retry either response in another workspace automatically.

Permissions

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

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

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.