Authentication

How authentication works in Vizco — JWT tokens for management, API keys for delivery.

Vizco uses two authentication methods for different use cases: JWT tokens for management operations and API keys for public widget delivery.

JWT authentication

JWT (JSON Web Tokens) are used for all management operations — creating projects, uploading assets, configuring widgets, and managing API keys.

Getting tokens

Register or log in to receive an access token and refresh token:

POST/api/auth/register
Response
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "role": "OWNER"
},
"organization": {
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "My Company",
  "slug": "my-company"
}
}

Using tokens

Include the access token in the Authorization header:

curl https://your-api.com/api/projects/{projectId} \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token lifecycle

  • Access token — Valid for 1 hour. Used for all authenticated requests.
  • Refresh token — Valid for 24 hours. Used to get a new access token without re-entering credentials.
POST/api/auth/refresh
Request body
{
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

API key authentication

API keys are used for public-facing operations — fetching published widgets and delivering assets to end users. They are project-scoped and designed for client-side use.

Key format

API keys follow the format pk_ followed by 32 hex characters:

pk_550e8400e29b41d4a716446655440000

Using API keys

Pass the key via the X-API-Key header:

curl https://your-api.com/api/v1/widgets/hero-carousel \
-H "X-API-Key: pk_550e8400e29b41d4a716446655440000"

Or as a query parameter:

curl "https://your-api.com/api/v1/widgets/hero-carousel?api_key=pk_550e8400e29b41d4a716446655440000"

Permissions

| Permission | Access level | |---|---| | READ | Can fetch published widgets | | READ_WRITE | Can fetch and modify resources |

Use READ permissions for client-side API keys. Only use READ_WRITE for server-side integrations.

Security

  • Keys are hashed with SHA-256 before storage. The full key is only returned once at creation time.
  • The keyPrefix (first 8 characters) is stored for identification in the dashboard.
  • Keys can have an optional expiration date and can be revoked at any time.

When to use which

| Scenario | Method | |---|---| | Dashboard / admin operations | JWT | | Android SDK widget rendering | API Key | | Server-side integrations | JWT or API Key (READ_WRITE) | | Asset delivery CDN | No auth required |

QuickstartOrganizations & Projects