Authentication

The QRCodeKIT API supports two authentication methods: JWT tokens and API keys. Choose the method that best fits your use case.

Authentication Methods

JWT Token Authentication

Use JWT tokens for web applications and user-based authentication. This method provides session management with automatic token refresh.

API Key Authentication

Use API keys for server-to-server communication, integrations, and automated systems. This method is more secure and doesn't require token management.

JWT Token Authentication

Login Endpoint

Authenticate by sending your credentials to the login endpoint:

curl 'https://api.v2.qrcodekit.com/api/login' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password",
    "rememberMe": false,
    "invitation": null
  }'

Response

{
  "token": "<JWT — redacted>",
  "refresh_token": "<64+ hex token — redacted>"
}

Using JWT Tokens

Include the JWT token in the Authorization header for all API requests:

curl 'https://api.v2.qrcodekit.com/api/qrs' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'X-Account-Id: YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json'

Token Management

• Access Token: Valid for 1 hour
• Refresh Token: Valid for 30 days
• Automatic Refresh: Use the refresh token to get a new access token when it expires

API Key Authentication

Getting an API Key

1. Log in to your QRCodeKIT dashboard
2. Navigate to Settings → API Keys
3. Generate a new API key
4. Copy the generated key (it won't be shown again)

Using API Keys

Include the API key in the X-Api-Key header for all API requests:

curl 'https://api.v2.qrcodekit.com/api/qrs' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Account-Id: YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json'

Required Headers

X-Account-Id Header

Since users can be part of many workspaces, the X-Account-Id header needs to be passed on every request that requires account context. This tells the system which workspace you are trying to perform the action in.

The X-Account-Id header is the IRI (Internationalized Resource Identifier) of a User Account resource that represents a user in a specific workspace.

curl 'https://api.v2.qrcodekit.com/api/qrs' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'X-Account-Id: /api/user-accounts/5020610e-ccdf-11ef-bf71-1e8259ecebcf' \
  -H 'Content-Type: application/json'

Example X-Account-Id:

/api/user-accounts/5020610e-ccdf-11ef-bf71-1e8259ecebcf

You can find your Account ID in the dashboard or in the API response when you authenticate.

Authentication Best Practices

JWT Token Best Practices

1. Store tokens securely - Use secure storage (not localStorage for production)
2. Handle token expiration - Implement automatic token refresh
3. Use HTTPS - Always use HTTPS in production
4. Rotate tokens regularly - Generate new tokens periodically

API Key Best Practices

1. Keep keys secret - Never expose API keys in client-side code
2. Use environment variables - Store keys in environment variables
3. Rotate keys regularly - Generate new keys and revoke old ones
4. Limit key permissions - Use keys with minimal required permissions

Error Handling

Authentication Errors

Common Error Responses

{
  "error": "Invalid credentials",
  "message": "The provided email or password is incorrect"
}

Example: Creating a Website QR Code

Here's a complete example of creating a Website QR code using JWT authentication:

# Step 1: Authenticate and get token
curl 'https://api.v2.qrcodekit.com/api/login' \
  -H 'content-type: application/json' \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password",
    "rememberMe": false
  }'

# Step 2: Create Website QR code
curl -X POST 'https://api.v2.qrcodekit.com/api/qrs' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'X-Account-Id: YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "typology": "/api/qr-typologies/0598466c-025c-11ef-83ba-06c4e69992ab",
    "input": {
      "url": "https://example.com"
    },
    "title": "My Website QR"
  }'

Response

{
  "@context": "/api/contexts/Qr",
  "@id": "/api/qrs/974aa45a-434f-11ef-8786-b28785f18bd7",
  "@type": "Qr",
  "pathName": "lV58V1",
  "title": "My Website QR",
  "state": 2,
  "typology": "/api/qr-typologies/0598466c-025c-11ef-83ba-06c4e69992ab",
  "assetUrl": "https://uqrmecdn.s3.us-east-2.amazonaws.com/v2-assets/dev/lV58V1-1721119458.svg",
  "input": {
    "url": "https://example.com"
  },
  "url": "https://uqr.to/lV58V1"
}

Next Steps

• Learn about QR code types
• Create your first Website QR
• Explore advanced features