API Authentication

API authentication uses a bearer token:

• Vault access keys, one per vault
• Resource-specific public tokens for a single key or certificate
• No unauthenticated access
• Secrets are never public

Authentication

Every Secryn API request authenticates with a bearer token in the Authorization header.

Secryn does not accept the access key as a query parameter, cookie, or session. Query parameters such as include, resource, and secrets select the response. They are not credentials.

Authentication Header

Every request must include:

Authorization: Bearer YOUR_TOKEN
Accept: application/json

If the header is missing or invalid, the API returns:

401 Unauthorized

Token Types

Secryn supports two types of API tokens:

• Vault Access Keys
• Public Resource Tokens (Keys and Certificates only)

1. Vault Access Keys

A vault access key is a machine credential for exactly one vault. It is created and rotated on that vault in the web interface. Secryn stores it as an HMAC-SHA256 hash keyed by APP_KEY.

The key:

• Does not inherit a user role
• Does not follow project RBAC or restricted-vault membership
• Can read secrets (including values), keys, and certificates in that vault
• Cannot create or update resources. The vault routes accept GET and HEAD only

Example - Vault Access

curl --request GET \
  --url "https://secryn.example.com/api/v1/vaults/{vault_id}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer VAULT_ACCESS_KEY"

Vault access keys are intended for:

• CI/CD pipelines
• Backend services
• Automation workflows
• MCP integrations

2. Public Resource Tokens

When a key or certificate is marked public:

• A resource-specific token is generated
• The vault access key is not required
• Access is restricted to that single resource
• User RBAC is not applied to that request
• The caller still sends Authorization: Bearer <resource public token>

Public tokens apply only to:

• Keys
• Certificates

Secrets can never be public.

Example - Public Certificate

curl --request GET \
  --url "https://secryn.example.com/api/v1/certificates/{certificate_id}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer RESOURCE_PUBLIC_TOKEN"

This token:

• Cannot list vault contents
• Cannot access secrets
• Cannot access other resources
• Is limited to that specific key or certificate

Authorization Model

Authentication verifies identity. Authorization determines access.

Vault access keys:

• Are scoped to one vault, not to a project or a role
• Can read every secret, key, and certificate in that vault
• Are rejected on routes other than GET and HEAD

Public Resource Tokens:

• Grant access to one specific resource
• Ignore vault-level RBAC
• Cannot escalate privileges

Unauthorized access attempts return:

403 Forbidden

Key Rotation and Revocation

Rotating Vault Access Keys

• Create a new access key
• Update automation systems
• Revoke the old key

Revoking Public Resource Tokens

To invalidate a public token:

• Disable public visibility on the resource
• Or delete the resource

A new token is generated if public visibility is re-enabled.

Security Best Practices

Secret values, secret versions, and audit before/after values are encrypted with Laravel encryption keyed by APP_KEY. Private keys use a SECRYN-PRIVATE-V1 envelope encrypted with that same key. A public resource token returns public material only, never a private key. See the security model. A vault access key can still read private keys in that vault, so limit which vaults you expose, and use HTTPS.

• Never commit tokens to source control
• Store tokens in CI/CD secret stores
• Rotate the vault access key when a client should lose access. Each vault has one key
• Monitor Request Logs for suspicious access

Error Responses

Important Notes

• All API access is logged in Request Logs.
• No unauthenticated access is allowed.
• Tokens are sent in the Authorization: Bearer header.
• Query parameters are never used for authentication.