How It Works

1. Your application is issued:

   • client_id
   • client_secret

2. Your system requests an access token from the Astragate Auth API

3. The access token is used to authorize all subsequent API requests

Client Credentials

After logging into the Astragate Developer Portal:

1. Navigate to Settings -> API & Integrations

2. Generate your:

   • Client ID
   • Client Secret

Security Best Practices

• Never expose your client_secret in frontend or mobile applications
• Store credentials in a secure vault (e.g., AWS Secrets Manager)
• Always use HTTPS when making API requests
• Rotate credentials periodically

Generate Access Token

Request

Endpoint

POST https://auth.dev.astragate.africa/v1/auth/token

Headers

Content-Type: application/x-www-form-urlencoded

Body

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Example (cURL)

curl -X POST https://auth.dev.astragate.africa/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600 seconds,
  "token_type": "Bearer",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."  // optional
}

Tip: Use the refresh_token to get a new access token without resending your client credentials.

Using the Access Token

Include the access token in the Authorization header for all API requests:

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Example API Call

curl -X POST https://api.dev.astragate.africa/sms/send \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "260XXXXXXXXX",
    "message": "Your transaction was successful"
  }'

Token Expiry

• Access tokens expire after the duration specified in expires_in
• Your system should cache and reuse the token until it expires
• Automatically request a new token when needed

Common Errors

Invalid Client Credentials

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Expired or Invalid Token

{
  "error": "invalid_token",
  "error_description": "The access token expired or is invalid"
}

Notes

• Do not request a new token for every API call
• Implement proper retry and error-handling logic
• Ensure secure storage of credentials at all times