API Keys

The API Keys endpoints allow you to generate, list, and manage API keys for authentication with tier-based rate limiting.

Generate an API Key

Creates a new API key for your account.

POST /v1/keys/generate

Authentication

Requires BearerAuth (session token).

Request Body

Field	Type	Required	Description
name	string	Yes	A descriptive name for the API key
tier	string	No	Subscription tier (defaults to account tier)

Request Example

cURL

curl -X POST "https://api.veriglob.com/v1/keys/generate" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key"
  }'

TypeScript

interface GenerateKeyRequest {
  name: string;
  tier?: string;
}

interface GenerateKeyResponse {
status: string;
message: string;
data: {
key_id: string;
api_key: string;
name: string;
tier: string;
rate_limit: number;
created_at: string;
last_used_at: string | null;
};
}

async function generateApiKey(
sessionToken: string,
name: string,
tier?: string
): Promise<GenerateKeyResponse> {
const response = await fetch('https://api.veriglob.com/v1/keys/generate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${sessionToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ name, tier })
});

if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}

return response.json();
}

// Usage
const result = await generateApiKey('your-session-token', 'Production API Key');
console.log('API Key:', result.data.api_key);
console.log('Rate Limit:', result.data.rate_limit, 'requests/min');

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type GenerateKeyRequest struct {
    Name string `json:"name"`
    Tier string `json:"tier,omitempty"`
}

type GenerateKeyResponse struct {
    Status  string `json:"status"`
    Message string `json:"message"`
    Data    struct {
        KeyID      string  `json:"key_id"`
        APIKey     string  `json:"api_key"`
        Name       string  `json:"name"`
        Tier       string  `json:"tier"`
        RateLimit  int     `json:"rate_limit"`
        CreatedAt  string  `json:"created_at"`
        LastUsedAt *string `json:"last_used_at"`
    } `json:"data"`
}

func GenerateApiKey(sessionToken, name, tier string) (*GenerateKeyResponse, error) {
    reqBody := GenerateKeyRequest{
        Name: name,
        Tier: tier,
    }
    jsonData, _ := json.Marshal(reqBody)

    req, err := http.NewRequest("POST", "https://api.veriglob.com/v1/keys/generate", bytes.NewBuffer(jsonData))
    if err != nil {
        return nil, err
    }

    req.Header.Set("Authorization", "Bearer "+sessionToken)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result GenerateKeyResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

func main() {
    result, _ := GenerateApiKey("your-session-token", "Production API Key", "")
    fmt.Printf("API Key: %s\n", result.Data.APIKey)
    fmt.Printf("Rate Limit: %d requests/min\n", result.Data.RateLimit)
}

Python

import requests
from typing import Optional

def generate_api_key(
session_token: str,
name: str,
tier: Optional[str] = None
) -> dict:
"""Generate a new API key."""
payload = {'name': name}
if tier:
payload['tier'] = tier

    response = requests.post(
        'https://api.veriglob.com/v1/keys/generate',
        headers={
            'Authorization': f'Bearer {session_token}',
            'Content-Type': 'application/json'
        },
        json=payload
    )
    response.raise_for_status()
    return response.json()

# Usage

result = generate_api_key('your-session-token', 'Production API Key')
print(f"API Key: {result['data']['api_key']}")
print(f"Rate Limit: {result['data']['rate_limit']} requests/min")

Response

201 Created

{
  "status": "success",
  "message": "API key generated successfully",
  "data": {
    "key_id": "key_abc123def456",
    "api_key": "vg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "Production API Key",
    "tier": "basic",
    "rate_limit": 100,
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": null
  }
}

Store Your API Key

The full api_key value is only shown once during creation. Store it securely - it cannot be retrieved later.

Error Responses

Status	Description
400	Invalid request body
401	Invalid or missing session token
403	Account key limit reached
429	Rate limit exceeded

---

List API Keys

Returns all API keys associated with your account.

GET /v1/keys

Authentication

Requires BearerAuth (session token).

Request Example

cURL

curl -X GET "https://api.veriglob.com/v1/keys" \
  -H "Authorization: Bearer your-session-token"

TypeScript

interface APIKeySummary {
  key_id: string;
  name: string;
  key_prefix: string;
  tier: string;
  rate_limit: number;
  created_at: string;
  last_used_at: string | null;
  active: boolean;
}

interface ListKeysResponse {
status: string;
message: string;
data: {
keys: APIKeySummary[];
total: number;
};
}

async function listApiKeys(sessionToken: string): Promise<ListKeysResponse> {
const response = await fetch('https://api.veriglob.com/v1/keys', {
headers: { 'Authorization': `Bearer ${sessionToken}` }
});

if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}

return response.json();
}

// Usage
const keys = await listApiKeys('your-session-token');
console.log('Total keys:', keys.data.total);
keys.data.keys.forEach(key => {
console.log(`- ${key.name} (${key.tier}): ${key.key_prefix}`);
});

Go

type APIKeySummary struct {
    KeyID      string  `json:"key_id"`
    Name       string  `json:"name"`
    KeyPrefix  string  `json:"key_prefix"`
    Tier       string  `json:"tier"`
    RateLimit  int     `json:"rate_limit"`
    CreatedAt  string  `json:"created_at"`
    LastUsedAt *string `json:"last_used_at"`
    Active     bool    `json:"active"`
}

type ListKeysResponse struct {
    Status  string `json:"status"`
    Message string `json:"message"`
    Data    struct {
        Keys  []APIKeySummary `json:"keys"`
        Total int             `json:"total"`
    } `json:"data"`
}

func ListApiKeys(sessionToken string) (*ListKeysResponse, error) {
    req, _ := http.NewRequest("GET", "https://api.veriglob.com/v1/keys", nil)
    req.Header.Set("Authorization", "Bearer "+sessionToken)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result ListKeysResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

Python

def list_api_keys(session_token: str) -> dict:
    """List all API keys for the account."""
    response = requests.get(
        'https://api.veriglob.com/v1/keys',
        headers={'Authorization': f'Bearer {session_token}'}
    )
    response.raise_for_status()
    return response.json()

# Usage

result = list_api_keys('your-session-token')
print(f"Total keys: {result['data']['total']}")
for key in result['data']['keys']:
print(f"- {key['name']} ({key['tier']}): {key['key_prefix']}")

Response

200 OK

{
  "status": "success",
  "message": "API keys retrieved successfully",
  "data": {
    "keys": [
      {
        "key_id": "key_abc123def456",
        "name": "Production API Key",
        "key_prefix": "vg_live_xxxx...xxxx",
        "tier": "basic",
        "rate_limit": 100,
        "created_at": "2024-01-15T10:30:00Z",
        "last_used_at": "2024-01-20T14:25:00Z",
        "active": true
      },
      {
        "key_id": "key_def789ghi012",
        "name": "Development Key",
        "key_prefix": "vg_test_xxxx...xxxx",
        "tier": "free",
        "rate_limit": 10,
        "created_at": "2024-01-10T08:00:00Z",
        "last_used_at": "2024-01-18T11:30:00Z",
        "active": true
      }
    ],
    "total": 2
  }
}

---

Get API Key Details

Returns details for a specific API key.

GET /v1/keys/{key_id}

Authentication

Requires BearerAuth (session token).

Path Parameters

Parameter	Type	Required	Description
key_id	string	Yes	The API key ID

Request Example

cURL

curl -X GET "https://api.veriglob.com/v1/keys/key_abc123def456" \
  -H "Authorization: Bearer your-session-token"

TypeScript

interface GetKeyResponse {
  status: string;
  message: string;
  data: {
    key_id: string;
    name: string;
    key_prefix: string;
    tier: string;
    rate_limit: number;
    created_at: string;
    last_used_at: string | null;
    active: boolean;
    usage: {
      requests_today: number;
      requests_this_month: number;
    };
  };
}

async function getApiKeyDetails(
sessionToken: string,
keyId: string
): Promise<GetKeyResponse> {
const response = await fetch(
`https://api.veriglob.com/v1/keys/${keyId}`,
{ headers: { 'Authorization': `Bearer ${sessionToken}` } }
);

if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}

return response.json();
}

// Usage
const key = await getApiKeyDetails('your-session-token', 'key_abc123def456');
console.log('Key name:', key.data.name);
console.log('Usage today:', key.data.usage.requests_today);

Go

type GetKeyResponse struct {
    Status  string `json:"status"`
    Message string `json:"message"`
    Data    struct {
        KeyID      string  `json:"key_id"`
        Name       string  `json:"name"`
        KeyPrefix  string  `json:"key_prefix"`
        Tier       string  `json:"tier"`
        RateLimit  int     `json:"rate_limit"`
        CreatedAt  string  `json:"created_at"`
        LastUsedAt *string `json:"last_used_at"`
        Active     bool    `json:"active"`
        Usage      struct {
            RequestsToday     int `json:"requests_today"`
            RequestsThisMonth int `json:"requests_this_month"`
        } `json:"usage"`
    } `json:"data"`
}

func GetApiKeyDetails(sessionToken, keyId string) (*GetKeyResponse, error) {
    url := fmt.Sprintf("https://api.veriglob.com/v1/keys/%s", keyId)
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+sessionToken)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result GetKeyResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

Python

def get_api_key_details(session_token: str, key_id: str) -> dict:
    """Get details for a specific API key."""
    response = requests.get(
        f'https://api.veriglob.com/v1/keys/{key_id}',
        headers={'Authorization': f'Bearer {session_token}'}
    )
    response.raise_for_status()
    return response.json()

# Usage

result = get_api_key_details('your-session-token', 'key_abc123def456')
print(f"Key name: {result['data']['name']}")
print(f"Usage today: {result['data']['usage']['requests_today']}")

Response

200 OK

{
  "status": "success",
  "message": "API key retrieved successfully",
  "data": {
    "key_id": "key_abc123def456",
    "name": "Production API Key",
    "key_prefix": "vg_live_xxxx...xxxx",
    "tier": "basic",
    "rate_limit": 100,
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": "2024-01-20T14:25:00Z",
    "active": true,
    "usage": {
      "requests_today": 245,
      "requests_this_month": 4521
    }
  }
}

---

Revoke an API Key

Permanently revokes an API key.

DELETE /v1/keys/{key_id}

Authentication

Requires BearerAuth (session token).

Path Parameters

Parameter	Type	Required	Description
key_id	string	Yes	The API key ID to revoke

Request Example

cURL

curl -X DELETE "https://api.veriglob.com/v1/keys/key_abc123def456" \
  -H "Authorization: Bearer your-session-token"

TypeScript

interface RevokeKeyResponse {
  status: string;
  message: string;
  data: {
    key_id: string;
    revoked_at: string;
  };
}

async function revokeApiKey(
sessionToken: string,
keyId: string
): Promise<RevokeKeyResponse> {
const response = await fetch(
`https://api.veriglob.com/v1/keys/${keyId}`,
{
method: 'DELETE',
headers: { 'Authorization': `Bearer ${sessionToken}` }
}
);

if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}

return response.json();
}

// Usage
const result = await revokeApiKey('your-session-token', 'key_abc123def456');
console.log('Revoked at:', result.data.revoked_at);

Go

type RevokeKeyResponse struct {
    Status  string `json:"status"`
    Message string `json:"message"`
    Data    struct {
        KeyID     string `json:"key_id"`
        RevokedAt string `json:"revoked_at"`
    } `json:"data"`
}

func RevokeApiKey(sessionToken, keyId string) (*RevokeKeyResponse, error) {
    url := fmt.Sprintf("https://api.veriglob.com/v1/keys/%s", keyId)
    req, _ := http.NewRequest("DELETE", url, nil)
    req.Header.Set("Authorization", "Bearer "+sessionToken)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result RevokeKeyResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

Python

def revoke_api_key(session_token: str, key_id: str) -> dict:
    """Permanently revoke an API key."""
    response = requests.delete(
        f'https://api.veriglob.com/v1/keys/{key_id}',
        headers={'Authorization': f'Bearer {session_token}'}
    )
    response.raise_for_status()
    return response.json()

# Usage

result = revoke_api_key('your-session-token', 'key_abc123def456')
print(f"Revoked at: {result['data']['revoked_at']}")

Response

200 OK

{
  "status": "success",
  "message": "API key revoked successfully",
  "data": {
    "key_id": "key_abc123def456",
    "revoked_at": "2024-02-01T10:00:00Z"
  }
}

Irreversible Action

Revoking an API key is permanent. Any applications using the revoked key will immediately lose access.

Error Responses

Status	Description
401	Invalid or missing session token
404	API key not found
429	Rate limit exceeded

---

Update API Key

Updates the name or settings of an API key.

PATCH /v1/keys/{key_id}

Authentication

Requires BearerAuth (session token).

Path Parameters

Parameter	Type	Required	Description
key_id	string	Yes	The API key ID to update

Request Body

Field	Type	Required	Description
name	string	No	New name for the API key

Request Example

cURL

curl -X PATCH "https://api.veriglob.com/v1/keys/key_abc123def456" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renamed Production Key"
  }'

TypeScript

interface UpdateKeyResponse {
  status: string;
  message: string;
  data: {
    key_id: string;
    name: string;
    updated_at: string;
  };
}

async function updateApiKey(
sessionToken: string,
keyId: string,
name: string
): Promise<UpdateKeyResponse> {
const response = await fetch(
`https://api.veriglob.com/v1/keys/${keyId}`,
{
method: 'PATCH',
headers: {
'Authorization': `Bearer ${sessionToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ name })
}
);

if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}

return response.json();
}

// Usage
const result = await updateApiKey(
'your-session-token',
'key_abc123def456',
'Renamed Production Key'
);
console.log('Updated at:', result.data.updated_at);

Go

type UpdateKeyRequest struct {
    Name string `json:"name"`
}

type UpdateKeyResponse struct {
    Status  string `json:"status"`
    Message string `json:"message"`
    Data    struct {
        KeyID     string `json:"key_id"`
        Name      string `json:"name"`
        UpdatedAt string `json:"updated_at"`
    } `json:"data"`
}

func UpdateApiKey(sessionToken, keyId, name string) (*UpdateKeyResponse, error) {
    reqBody := UpdateKeyRequest{Name: name}
    jsonData, _ := json.Marshal(reqBody)

    url := fmt.Sprintf("https://api.veriglob.com/v1/keys/%s", keyId)
    req, _ := http.NewRequest("PATCH", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+sessionToken)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result UpdateKeyResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

Python

def update_api_key(session_token: str, key_id: str, name: str) -> dict:
    """Update an API key's name."""
    response = requests.patch(
        f'https://api.veriglob.com/v1/keys/{key_id}',
        headers={
            'Authorization': f'Bearer {session_token}',
            'Content-Type': 'application/json'
        },
        json={'name': name}
    )
    response.raise_for_status()
    return response.json()

# Usage

result = update_api_key('your-session-token', 'key_abc123def456', 'Renamed Production Key')
print(f"Updated at: {result['data']['updated_at']}")

Response

200 OK

{
  "status": "success",
  "message": "API key updated successfully",
  "data": {
    "key_id": "key_abc123def456",
    "name": "Renamed Production Key",
    "updated_at": "2024-02-01T10:00:00Z"
  }
}

---

Rate Limit Tiers

Tier	Requests/Minute	Description
free	10	Free tier for testing and development
basic	100	Basic tier for small applications
pro	1,000	Professional tier for production use
enterprise	10,000	Enterprise tier for high-volume applications

Rate Limit Headers

All API responses include rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests per minute
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Handling Rate Limits

When you exceed your rate limit, you’ll receive a 429 Too Many Requests response:

{
  "status": "error",
  "message": "Rate limit exceeded",
  "error": "You have exceeded your rate limit of 100 requests per minute. Please wait 45 seconds before retrying."
}

Best Practices:

1. Monitor the X-RateLimit-Remaining header
2. Implement exponential backoff when approaching limits
3. Cache responses where appropriate
4. Batch operations when possible

---

API Key Formats

Veriglob API keys follow these patterns:

Environment	Prefix	Example
Production	vg_live_	vg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Test	vg_test_	vg_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx