Authentication

Semaswift supports multiple authentication methods to fit different use cases. All API requests require authentication except for public endpoints like health checks.

Authentication Methods

1. JWT Bearer Tokens (Recommended for Web/Mobile)

JWT tokens are the primary authentication method for web and mobile applications.

Getting a Token

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Token

Include the token in the Authorization header:

curl https://api.semaswift.africa/api/v1/users \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJSUzI1NiIs..."
}

2. Personal Access Tokens (PAT)

PATs are ideal for server-to-server communication and CI/CD pipelines.

Creating a PAT

1. Go to Settings > API Keys in your dashboard
2. Click Create New Token
3. Set a name and expiration date
4. Copy the token (it won't be shown again)

Using a PAT

curl https://api.semaswift.africa/api/v1/users \
  -H "X-API-Key: pat_live_xxxxxxxxxxxxx"

Or in the Authorization header:

curl https://api.semaswift.africa/api/v1/users \
  -H "Authorization: Bearer pat_live_xxxxxxxxxxxxx"

3. OAuth2/OIDC (Third-Party Integrations)

For third-party applications that need to access Semaswift on behalf of users.

Authorization Code Flow

1. Redirect user to authorize:

https://auth.semaswift.africa/oauth2/auth?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  scope=openid profile email&
  state=random_state_value

2. Exchange code for tokens:

POST https://auth.semaswift.africa/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://your-app.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Available Scopes

Scope	Description
openid	Required for OIDC
profile	User profile information
email	User email address
offline_access	Enables refresh tokens

Token Claims

JWT tokens contain the following claims:

{
  "sub": "usr_123456",
  "iss": "https://auth.semaswift.africa",
  "aud": "semaswift-api",
  "exp": 1704067200,
  "iat": 1704063600,
  "organization_id": "org_789",
  "roles": ["admin", "agent"],
  "permissions": ["user:read", "user:write", "ticket:read"]
}

Security Best Practices

1. Never expose tokens in URLs - Always use headers
2. Use HTTPS - All API requests must use HTTPS in production
3. Rotate tokens regularly - Set reasonable expiration times
4. Store tokens securely - Use secure storage mechanisms
5. Use appropriate scopes - Request only needed permissions

Multi-Factor Authentication (MFA)

When MFA is enabled, the login flow includes an additional step:

# Step 1: Initial login
POST /api/v1/auth/login
{
  "email": "[email protected]",
  "password": "your-password"
}

# Response indicates MFA required
{
  "mfa_required": true,
  "mfa_token": "mfa_xxxxx",
  "mfa_methods": ["totp", "sms"]
}

# Step 2: Submit MFA code
POST /api/v1/auth/mfa/verify
{
  "mfa_token": "mfa_xxxxx",
  "code": "123456",
  "method": "totp"
}

Error Responses

Status	Code	Description
401	INVALID_CREDENTIALS	Email or password incorrect
401	TOKEN_EXPIRED	Access token has expired
401	TOKEN_INVALID	Token is malformed or revoked
403	INSUFFICIENT_PERMISSIONS	Token lacks required permissions
429	RATE_LIMITED	Too many authentication attempts

Next Steps

• Making Requests - Learn about request formatting
• Errors - Understand error handling
• Rate Limiting - API rate limits