Authentication

The GoValid API supports multiple authentication methods for different use cases.

Authentication Methods

Method	Use Case	Best For
JWT Bearer Token	User sessions	Mobile apps, web clients
API Key	Server-to-server	Backend integrations
Session	Browser	Web admin panels

---

JWT Bearer Token

JSON Web Tokens for user-authenticated requests.

Getting a Token

curl -X POST https://api.govalid.org/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLC...",
  "refresh": "eyJ0eXAiOiJKV1QiLC...",
  "user": {
    "id": 123,
    "email": "[email protected]"
  }
}

Using the Token

Include the token in the Authorization header:

curl https://api.govalid.org/api/v1/qr/ \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLC..."

Token Lifetime

Token Type	Lifetime
Access Token	60 minutes
Refresh Token	7 days

Refreshing Tokens

curl -X POST https://api.govalid.org/api/v1/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{
    "refresh": "eyJ0eXAiOiJKV1QiLC..."
  }'

---

API Keys

For server-to-server integrations without user context.

Creating an API Key

1. Log in to GoValid Dashboard
2. Navigate to Account → API Keys
3. Click Create New Key
4. Set permissions and expiration
5. Copy the key (shown only once)

Using API Keys

Option 1: Bearer format (recommended)

curl https://api.govalid.org/api/v1/qr/ \
  -H "Authorization: Bearer gv_your_api_key_here"

Option 2: X-API-Key header

curl https://api.govalid.org/api/v1/qr/ \
  -H "X-API-Key: gv_your_api_key_here"

Option 3: Legacy format

curl https://api.govalid.org/api/v1/qr/ \
  -H "Authorization: Api-Key gv_your_api_key_here"

API Key Features

• Scoped permissions (read, write, delete)
• Rate limiting per key
• Usage tracking and analytics
• Optional expiration date
• Can be revoked anytime

---

Security Best Practices

Do's

• Store tokens/keys securely (environment variables, secret managers)
• Use HTTPS for all requests
• Implement token refresh before expiration
• Set appropriate API key permissions
• Rotate API keys periodically

Don'ts

• Never expose tokens in client-side code
• Don't commit API keys to version control
• Don't share keys between environments
• Don't use long-lived tokens for web apps

---

Error Responses

401 Unauthorized

{
  "detail": "Authentication credentials were not provided."
}

Causes:

• Missing Authorization header
• Invalid or expired token
• Revoked API key

403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

Causes:

• Insufficient API key permissions
• Account restrictions
• Feature not available on your plan

---

Next Steps

• Quick Start - Make your first authenticated request
• Code Examples - Authentication in different languages