Credential Provisioning

Quick Reference

WhatUnderstand and manage A55 API credentials

WhyProper credential management prevents security incidents and integration failures

Reading Time8 min

DifficultyBeginner

PrerequisitesSandbox or production account

Credential Types

Credential	Format	Purpose
entity_uuid	UUID v4	Identifies your business entity in A55
merchant_uuid	UUID v4	Identifies a specific merchant configuration
client_id	String	OAuth2 client identifier for authentication
client_secret	String	OAuth2 client secret — keep this private
wallet_uuid	UUID v4	Identifies a wallet that holds charges

Hierarchy

Entity (entity_uuid)
└── Merchant (merchant_uuid)
    ├── Wallet A (wallet_uuid)
    │   ├── Charge 1
    │   └── Charge 2
    └── Wallet B (wallet_uuid)
        └── Charge 3

A single entity can have multiple merchants (e.g., different business lines), and each merchant can have multiple wallets.

Sandbox vs Production

Aspect	Sandbox	Production
API base URL	https://sandbox.api.a55.tech	https://api.a55.tech
Auth URL	https://auth.sandbox.a55.tech	https://auth.a55.tech
Cognito pool	Separate pool	Separate pool
Credentials	Different client_id/client_secret	Different client_id/client_secret
Real money	No	Yes
Test cards	Accepted	Rejected

Credentials are not interchangeable

Sandbox credentials do not work in production and vice versa. Each environment has its own Cognito user pool with separate client IDs and secrets.

How to Rotate Credentials

1. Contact tech.services@a55.tech requesting a credential rotation
2. A55 generates a new client_secret while keeping your client_id unchanged
3. Both old and new secrets remain valid for a 24-hour grace period
4. Update your environment variables and deploy
5. Confirm the new secret works, then notify A55 to revoke the old one

# After receiving new credentials
export A55_CLIENT_SECRET="new_rotated_secret_value"

# Verify authentication works
curl -s -X POST "https://auth.sandbox.a55.tech/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=${A55_CLIENT_ID}" \
  -d "client_secret=${A55_CLIENT_SECRET}" \
  -d "scope=api/readwrite" | python3 -m json.tool

Security Best Practices

Never commit secrets to version control

# .gitignore
.env
.env.local
.env.production

Use environment variables

# .env (local development only — never commit this file)
A55_CLIENT_ID=your_client_id
A55_CLIENT_SECRET=your_client_secret

# In your application
import os
client_id = os.environ["A55_CLIENT_ID"]

Rotate every 90 days

Set a calendar reminder. Credential rotation limits the blast radius of a leaked secret.

Limit access

• Only backend services should have access to client_secret
• Never expose credentials in frontend code, logs, or error messages
• Use your cloud provider's secret manager (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager)

Monitor usage

• Track token issuance in your logs
• Alert on authentication failures — they may indicate leaked or revoked credentials
• Review API access patterns monthly

A55 uses the OAuth2 client_credentials grant type, designed for machine-to-machine (M2M) authentication:

1. Your server sends client_id + client_secret to the token endpoint
2. A55's Cognito returns a JWT access token valid for 3600 seconds (1 hour)
3. You include this token as Authorization: Bearer <token> in every API request
4. Before the token expires, your code must request a new one

There is no user interaction, no authorization code, no redirect — this is a direct credential exchange suitable for backend services.

Token structure: The JWT contains your entity_uuid, granted scopes, and expiration. You can decode it (it is base64), but you do not need to — pass it as-is to the API.

Quickstart →Use your credentials to make a chargeAuthentication →Token lifecycle and refresh flowGo-Live Checklist →Verify production readiness