API Authentication & Getting Started

API Authentication & Getting Started

The KyberAccess REST API allows you to integrate visitor management into your existing systems, automate workflows, and build custom applications. Whether you want to programmatically create pre-registrations, pull visitor data into a BI tool, or trigger actions in response to check-in events, the API provides full access to KyberAccess functionality.

This guide covers how to obtain API credentials, authenticate your requests, and make your first API call.

Prerequisites

• A KyberAccess account with Owner or Admin role
• Basic familiarity with REST APIs and HTTP requests
• A tool for making API calls (e.g., cURL, Postman, or your programming language's HTTP library)

Generating API Keys

1. Log in to your KyberAccess dashboard at app.kyberaccess.com.
2. Navigate to Settings from the left sidebar.
3. Click API & Integrations under the Developer section.
4. Click + Generate API Key.
5. Enter a descriptive name for the key (e.g., "CRM Integration" or "BI Dashboard").
6. Select the key's permission scope:
   • Read Only — Can retrieve data but cannot create, update, or delete
   • Read/Write — Full access to create, read, update, and delete resources
   • Custom — Select specific endpoints and methods
7. Optionally set an expiration date for the key.
8. Click Generate.
9. Copy the API key immediately — it will only be displayed once.

Important: Store your API key securely. Do not expose it in client-side code, public repositories, or unencrypted files. Treat it like a password.

Authentication Methods

KyberAccess supports two authentication methods:

Method 1: JWT Bearer Token (Recommended)

Use your API key to obtain a short-lived JWT token, then use that token for subsequent requests.

Step 1: Obtain a JWT Token

POST /api/v1/auth/token
Content-Type: application/json

{
  "api_key": "your-api-key-here"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-01-15T12:00:00Z",
  "token_type": "Bearer"
}

Step 2: Use the JWT in Requests

Include the token in the Authorization header:

GET /api/v1/visitors
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT tokens expire after 1 hour. When a token expires, request a new one using your API key.

Method 2: API Key in Header

For simpler integrations, you can pass the API key directly in a header:

GET /api/v1/visitors
X-API-Key: your-api-key-here

Note: Direct API key authentication is simpler but less secure than JWT. We recommend JWT for production integrations.

Base URL

All API requests use the following base URL:

https://api.kyberaccess.com/api/v1

All endpoints require HTTPS. HTTP requests are rejected.

Making Your First API Call

Let's retrieve a list of today's visitors:

Using cURL

curl -X GET "https://api.kyberaccess.com/api/v1/visitors?date=today" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Using Postman

1. Open Postman and create a new GET request.
2. Enter the URL: https://api.kyberaccess.com/api/v1/visitors?date=today
3. Go to the Authorization tab, select Bearer Token, and paste your JWT.
4. Click Send.
5. The response appears in the body panel.

Sample Response

{
  "data": [
    {
      "id": "vis_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "host": {
        "id": "usr_xyz789",
        "name": "John Doe",
        "department": "Engineering"
      },
      "check_in_time": "2025-01-15T09:30:00Z",
      "check_out_time": null,
      "status": "checked_in",
      "purpose": "Meeting",
      "id_scanned": true,
      "nda_signed": true,
      "badge_number": "V-0042",
      "location_id": "loc_001"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 25
  }
}

Rate Limits

To ensure fair usage, the API enforces rate limits:

When you exceed the rate limit, you'll receive a 429 Too Many Requests response with headers indicating when you can retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312200

Pagination

List endpoints return paginated results. Use query parameters to control pagination:

• page — Page number (default: 1)
• per_page — Results per page (default: 25, max: 100)

Example:

GET /api/v1/visitors?page=2&per_page=50

The response includes a meta object with pagination details:

{
  "meta": {
    "total": 350,
    "page": 2,
    "per_page": 50,
    "total_pages": 7
  }
}

Error Handling

The API uses standard HTTP status codes:

Error responses include a descriptive message:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'email' field must be a valid email address.",
    "details": [
      {
        "field": "email",
        "issue": "Invalid format"
      }
    ]
  }
}

API Key Management

Viewing Active Keys

1. Go to Settings → API & Integrations.
2. The API Keys section lists all active keys with:
   • Key name
   • Last 4 characters of the key
   • Permission scope
   • Last used date
   • Expiration date

Revoking a Key

1. Click the Revoke button next to the key.
2. Confirm the revocation.
3. The key is immediately invalidated and cannot be used.

Warning: Revoking a key immediately breaks any integrations using that key. Ensure you have a replacement key configured before revoking.

Rotating Keys

For security best practices, rotate your API keys periodically:

1. Generate a new key.
2. Update your integrations to use the new key.
3. Verify everything works with the new key.
4. Revoke the old key.

SDKs and Libraries

KyberAccess provides official SDKs for popular languages:

• JavaScript/Node.js — npm install kyberaccess-sdk
• Python — pip install kyberaccess
• Ruby — gem install kyberaccess
• PHP — composer require kyberaccess/sdk

SDKs handle authentication, pagination, and error handling automatically.

Quick Start with Node.js

const KyberAccess = require('kyberaccess-sdk');

const client = new KyberAccess({
  apiKey: 'your-api-key-here'
});

// List today's visitors
const visitors = await client.visitors.list({ date: 'today' });
console.log(visitors.data);

Sandbox Environment

KyberAccess provides a sandbox environment for testing:

• Sandbox URL: https://sandbox.kyberaccess.com/api/v1
• Sandbox keys are separate from production keys
• Sandbox data resets every 24 hours
• Use sandbox for development and testing before going to production

To create a sandbox key:

1. Go to Settings → API & Integrations.
2. Click the Sandbox tab.
3. Click Generate Sandbox Key.

Troubleshooting

Next Steps

• API Reference: Visitors & Check-Ins — Detailed endpoint documentation for visitor operations
• Webhook Configuration — Set up real-time event notifications
• Explore the Postman Collection — Download from Settings → API & Integrations → Postman Collection