Skip to content

API Keys

API keys provide programmatic access to the Mayo ASPM REST API. Use them to integrate Mayo ASPM with CI/CD pipelines, custom scripts, and third-party tools.

Key format

Mayo ASPM API keys follow a predictable format for easy identification:

mayo_ak_<32 character random string>

Example:

mayo_ak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Prefix-based identification

The mayo_ak_ prefix makes it easy to identify Mayo ASPM keys in logs, secrets scanners, and environment variables. If you see this prefix in a scan result, it's a Mayo ASPM API key.

Creating an API key

  1. Navigate to Settings > Integrations > API Keys.
  2. Click Create API Key.
  3. Configure the key:
Field Description Required
Name A descriptive name (e.g., "CI Pipeline", "Airflow Prod") Yes
Expiry When the key expires (30 days, 90 days, 1 year, no expiry) Yes
Permissions Which API operations the key can perform Yes
  1. Click Create.
  2. Copy the key immediately — it will not be shown again.

Store securely

The full API key is displayed only once at creation time. Store it in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager, GitHub Secrets). If you lose it, you must revoke and create a new one.

Permissions

API keys are scoped to specific permissions:

Permission Allows
scans:read View scan results and finding data
scans:write Trigger scans and upload results
findings:read View findings
findings:write Update finding status
policies:read View policies
policies:write Create and edit policies
projects:read View projects and assets
projects:write Create and manage projects
tickets:read View generated tickets
tickets:write Generate and manage tickets
admin Full organization administration

Least privilege

Grant only the permissions the key needs. A CI pipeline that only triggers scans should have scans:write and scans:read — nothing else.

Using an API key

Include the API key in the Authorization header:

curl https://mayoaspm.com/api/findings \
  -H "Authorization: Bearer mayo_ak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Or as an X-API-Key header:

curl https://mayoaspm.com/api/findings \
  -H "X-API-Key: mayo_ak_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Both methods are equivalent. The Authorization: Bearer format is recommended for consistency with other authentication methods.

Managing API keys

Viewing keys

Navigate to Settings > Integrations > API Keys to see all keys:

Column Description
Name Key name
Created Creation date
Expires Expiry date
Last used Last API call timestamp
Permissions Granted permissions
Status Active or Revoked

Info

The key value itself is never displayed after creation. Only the name, metadata, and a masked suffix are shown.

Revoking a key

  1. Find the key in the list.
  2. Click Revoke.
  3. Confirm revocation.

Revocation is immediate. Any API calls using the revoked key will return 401 Unauthorized.

Warning

Revocation cannot be undone. If you revoke a key by mistake, create a new one and update all integrations that used the old key.

Rotating keys

To rotate a key without downtime:

  1. Create a new key with the same permissions.
  2. Update your integrations to use the new key.
  3. Verify the new key works.
  4. Revoke the old key.

Security best practices

  1. Set expiry dates — avoid "no expiry" keys unless absolutely necessary.
  2. Use descriptive names — so you know what each key is for when reviewing.
  3. Rotate regularly — rotate keys every 90 days.
  4. Monitor usage — check "Last used" timestamps; revoke unused keys.
  5. Never commit keys — use environment variables or secrets managers.
  6. Use separate keys per environment — don't share keys between staging and production.

Rate limits

API key requests are subject to rate limits based on your plan tier. See Rate limits for details.

Audit trail

All API key usage is logged in the organization audit trail:

  • Key creation and revocation events
  • API calls made with each key (endpoint, timestamp, response code)
  • Failed authentication attempts

Next steps