Best Practices
The Secure Service Account (SSA) flow is designed to be drop-in for most server-to-server scenarios, but a small number of practices make the difference between an integration that ships smoothly and one that surfaces support tickets six months later. This page collects the patterns real production deployments have converged on.
Where a topic is covered in depth elsewhere in the Developer’s Guide, this page summarises the practice and links out. For ISV integrations that serve many customers under one Client ID, see Tenant Isolation for ISV Integrations.
Note:
This page assumes you have completed the Get Started with SSA tutorial and have a working SSA integration in at least a development environment. The practices below help you harden that integration for production.
Naming Conventions
A consistent, descriptive name makes it easy for IT admins to identify what an SSA is for at a glance, and trivial to audit access patterns later. Use a format that makes the account’s purpose clear.
Enforced rules
These constraints are enforced when you create an SSA:
- Use only lowercase letters (a–z), numbers (0–9), underscores (
_), and hyphens (-). - The name must start and end with a letter or number.
- Length must not exceed 100 characters.
- Do not use spaces, special characters (like
@,!,#,$), or emojis.
Naming conventions
- Include the service, integration, company, or purpose in the name.
- Avoid generic names like
robot123ortestBot. - Use hyphens or underscores to separate logical parts for readability.
We recommend the following format:
[service|integration|config]-[company]-[purpose]
Examples:
service-acc-reportsintegration-mycompany-daily_datasync(sections are separated by hyphens;daily_datasyncis the purpose, which uses an underscore.)config-admin_tasks(company is omitted)
A consistent naming convention helps IT quickly identify an SSA’s function and manage access and permissions appropriately.
If you operate an ISV-style integration where one Client ID serves many customers, see Tenant Isolation for ISV Integrations for multi-tenant naming and the Robot-per-Tenant pattern.
Key Management
Rotate keys on a fixed cadence
Rotate SSA signing keys regularly — 90 days is a safe maximum, 30 days is preferred. SSA supports multiple active keys simultaneously, so you can roll a new key in alongside the old one, switch traffic over, then disable the old key without downtime.
Store private keys in a secrets manager, not on disk
Use AWS Secrets Manager, Google Secret Manager, Azure Key Vault, HashiCorp Vault, or an equivalent service. .pem files on application servers survive snapshots, backups, and host migrations far too easily.
Separate keys per environment
Maintain one keypair per environment (development, staging, production). A leaked development key should never grant access to production data.
Have a revocation playbook ready
If a key is suspected compromised, your incident response should be able to:
- Disable the affected key using Enable or Disable Key.
- Confirm the disable propagated by attempting an assertion exchange with the old key (it should fail).
- Audit recent activity by that SSA in APS audit logs.
- Issue a new key and update production secrets.
Document this playbook before you need it.
Error Handling and Resilience
The SSA token exchange is generally reliable, but production systems need to be resilient to the failure modes that do exist:
- Always send the final three-legged access token to business APIs, not the two-legged token from step 1 of the handshake. Sending the wrong token is the most common cause of “SSA does not work with X” reports — see Token type confusion.
- Implement retry with exponential backoff for
HTTP 429(rate limited) andHTTP 5xxresponses. - Treat
HTTP 401on a previously-working token as “token expired” — re-acquire and retry once. - Treat
HTTP 403as a permission problem, not a token problem — do not retry; surface to the user or to alerting.
See Error Handling for the full list of error responses.
Rate Limiting
The JWT exchange endpoint enforces 10 requests per minute. The business APIs you call afterwards have their own limits. The practical implications:
- Cache the three-legged access token for its full lifetime (one hour) rather than minting one per request. Cache other API responses where appropriate to avoid unnecessary calls.
- Distribute scheduled jobs and requests evenly across time rather than triggering all robots in a burst at the top of the hour.
- Use efficient polling intervals when checking for status changes instead of tight loops.
- Monitor your
429rate and reduce concurrency before APS throttles you.
For the per-operation limits and the full set of rate-limit recommendations, see SSA Rate Limits and APS Rate Limits.
Monitoring and Audit
For each SSA in production, track:
- Token-exchange success rate and
429rate. - Per-robot API call volume and error rate.
- Time-since-last-rotation for each signing key.
- Hub or Project membership changes for each robot. A robot quietly removed from a project by a customer admin will fail silently from your side.
APS audit logs are the source of truth for which SSA made which API call. Forward them into your existing observability stack rather than relying on application logs alone.