API Reference

REST API for programmatic access to TOTP codes

Authentication

All API requests must include an Authorization header with a Bearer token:

Authorization: Bearer YOUR_API_KEY

API keys can be created in the API Keys section of your dashboard.

Base URL

https://api.cloud2fa.com/api/v1

Endpoints

GET/api/v1/secrets

Get list of all secrets

Response

{
  "secrets": [
    {
      "id": "secret_123",
      "name": "GitHub",
      "issuer": "github.com",
      "category": "Development",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

GET/api/v1/secrets/:id

Get secret by ID

Response

{
  "id": "secret_123",
  "name": "GitHub",
  "issuer": "github.com",
  "category": "Development",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30,
  "createdAt": "2024-01-15T10:30:00Z"
}

GET/api/v1/secrets/:id/code

Get current TOTP code

Response

{
  "code": "123456",
  "remaining": 15,
  "period": 30
}

POST/api/v1/secrets

Create a new secret

Request Body

{
  "name": "GitHub",
  "secret": "JBSWY3DPEHPK3PXP",
  "issuer": "github.com",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30
}

Response

{
  "id": "secret_456",
  "name": "GitHub",
  "issuer": "github.com",
  "createdAt": "2024-01-15T10:30:00Z"
}

DELETE/api/v1/secrets/:id

Delete a secret

Response

{
  "success": true
}

Error Codes

Code	Description
`400`	Bad Request — check parameters
`401`	Unauthorized — check API key
`403`	Forbidden — insufficient permissions
`404`	Resource not found
`500`	Internal server error

Rate Limiting

The API has a limit of 100 requests per minute per API key. When the limit is exceeded, error 429 will be returned.