API Tokens

Create and manage machine tokens for headless spec publishing from CI/CD pipelines.

What are API tokens?

API tokens let CI/CD pipelines publish specs to SpecVault without interactive login. A token is a long random string that authenticates as the admin user for API calls only — it cannot be used to log in to the dashboard UI.

Tokens are bcrypt-hashed before storage. The plain-text value is shown exactly once at creation time and cannot be retrieved afterwards. If a token is lost, revoke it and create a new one.

Creating a token

1. Navigate to API Tokens in the top navigation bar.
2. Click New Token.
3. Enter a descriptive name (e.g. github-actions-prod or gitlab-ci-staging).
4. Click Create. The plain-text token value is shown in a one-time modal.
5. Copy the token immediately and store it in your CI/CD secret store (GitHub Secrets, GitLab CI Variables, etc.).

Using a token in API calls

Pass the token as a Bearer token in the Authorization header:

curl -X POST https://specvault.sentinelflux.in/api/services/<service-id>/specs \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"spec_url": "https://api.yourcompany.com/openapi.json"}'

Or when uploading a file directly:

curl -X POST https://specvault.sentinelflux.in/api/services/<service-id>/specs \
  -H "Authorization: Bearer <your-token>" \
  -F "file=@openapi.yaml"

Finding the service ID

The service ID is shown on the service detail page under the Settings tab, and also appears in the URL when viewing a service: /services/<service-id>.

Revoking a token

On the API Tokens page, click the Revoke button next to any token. Revocation is immediate — subsequent requests using that token will receive a 401 Unauthorized response.

Rotate tokens regularly, especially after team members leave or if a token may have been exposed in logs or version control.

Token security best practices

• Use one token per pipeline / environment (e.g. separate tokens for staging vs production CI)
• Store tokens in your CI/CD secret manager, never in source code
• Give tokens descriptive names so you can identify and revoke the right one quickly
• Check your application logs — tokens should never appear in log output
• Revoke any token that was accidentally committed to a repository immediately