API Authentication

This version correctly reflects the Secryn authentication model:

• Bearer token only
• Vault Access Keys
• Resource-specific Public Tokens
• No unauthenticated access
• Secrets never public

Authentication

All Secryn API requests must be authenticated using a Bearer token.

Secryn does not support session-based authentication, cookies, or query-string tokens. All authentication is performed using the Authorization header.

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

Vault Access Keys are machine credentials scoped to a project.

They:

• Are created in the Web interface
• Inherit permissions based on assigned role
• Respect RBAC and restricted vault rules
• Can access secrets, keys, and certificates within scope
• Can list vault resources (if permitted)

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 as Public during creation:

• A resource-specific token is generated
• Vault-level access is not required
• Access is restricted to that single resource
• RBAC is bypassed for that resource only

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:

• Follow project-level RBAC
• Respect restricted vault boundaries
• Can be scoped by role

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

• Never commit tokens to source control
• Store tokens in CI/CD secret stores
• Rotate tokens regularly
• Disable unused access keys
• Monitor Request Logs for suspicious access

Error Responses

Important Notes

• All API access is logged in Request Logs.
• No unauthenticated access is allowed.
• Tokens must always be sent via Authorization header.
• Query parameters are never used for authentication.