# Security API

## Overview

The VerifEye Security API provides authentication and token management services for secure access to the VerifEye ecosystem.

The Security API enables you to:
- Generate JWT tokens for client-side authentication
- Retrieve server UTC time for synchronization
- Validate API credentials
- Monitor API health status

!!!tip
This API is intended for **server-side use only**. Using it directly from the client side would expose it to potential misuse and abuse.
!!!

## Base URLs

| Region | Base URL |
|--------|----------|
| **EU** | `https://security-api-eu.realeyes.ai/v1/` |
| **US** | `https://security-api-us.realeyes.ai/v1/` |

---

## API Endpoints

### Get JWT Token

Generate a JWT token for authentication.

**Endpoint:** `GET /v1/token/get`

**Authentication:** API Key only (Bearer tokens are not allowed for this endpoint)

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `expirationInSeconds` | integer | No | 900 | The JWT token expiration in seconds. Minimum value is 60. Maximum value is 3600. |

**Response Example:**

```json
{
  "expirationUtcTime": "2026-01-26T14:30:00.000Z",
  "token": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9..."
}
```

**Response Fields:**

| Name | Type | Description |
|-----------|------|----------|---------|-------------|
| `expirationUtcTime` | string (datetime ISO 8601) | The UTC time when the token expires |
| `token` | string | The authentication token used to authorize requests. |

**Example Request:**

```bash
curl -X GET "https://security-api-eu.realeyes.ai/v1/token/get?expirationInSeconds=3600" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"
```

**Response Codes:**
- `200` - Success
- `401` - Unauthorized (invalid or missing API key)

---

### Get Server UTC Time

Retrieve the current server time in UTC for time synchronization.

**Endpoint:** `GET /v1/datetime/utc-now`

**Authentication:** API Key or Bearer Token

**Response Example:**

```json
{
  "utcNow": "2026-01-26T13:45:30.1234567Z"
}
```

**Response Fields:**

| Name | Type | Description |
|-----------|------|----------|---------|-------------|
| `utcNow` | string (datetime ISO 8601) | UtcNow time of the server in ISO 8601. |

**Example Request:**

```bash
curl -X GET "https://security-api-eu.realeyes.ai/v1/datetime/utc-now" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"
```

**Response Codes:**
- `200` - Success
- `401` - Unauthorized
- `403` - Forbidden (valid auth but account not found)

---

### Health Check

Check the API health status.

**Endpoint:** `GET /v1/healthz`

**Authentication:** None required

**Response Example:**

```
2026-01-26T13:45:30.1234567Z
```

**Response Content:**

The server UTC time (ISO 8601)

**Example Request:**

```bash
curl -X GET "https://security-api-eu.realeyes.ai/v1/healthz"
```

**Response Codes:**
- `200` - API is healthy

---

## Common Response Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Missing or invalid authentication |
| `403` | Forbidden - Valid authentication but account not found or insufficient permissions |
| `500` | Internal Server Error |

---

## Swagger Documentation

Interactive API documentation is available via Swagger UI:

- **EU**: [https://security-api-eu.realeyes.ai/swagger](https://security-api-eu.realeyes.ai/swagger)
- **US**: [https://security-api-us.realeyes.ai/swagger](https://security-api-us.realeyes.ai/swagger)

---

*Last updated: 2026-01-26*