Internal Auth API

Internal API

These endpoints are for internal use by the Veriglob dashboard and mobile applications. They handle user authentication and session management.

The Internal Auth API provides endpoints for user registration, login, logout, and session management.

User Registration

Creates a new user account with email and password.

POST /internal/v1/auth/register

Authentication

Requires InternalSecret.

Request Body

Field	Type	Required	Description
email	string	Yes	User’s email address
password	string	Yes	Password (min 8 characters)
name	string	No	User’s display name

Request Example

curl -X POST "https://api.veriglob.com/internal/v1/auth/register" \
  -H "X-Internal-Secret: your-internal-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure-password",
    "name": "New User"
  }'

Response

201 Created

{
  "status": "success",
  "message": "User registered successfully",
  "data": {
    "user_id": "user_abc123def456",
    "email": "newuser@example.com",
    "name": "New User",
    "tier": "free",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Responses

Status	Description
400	Invalid email format or password too weak
409	Email already registered

---

User Login

Authenticates a user with email and password, returns a session token.

POST /internal/v1/auth/login

Authentication

None required.

Request Body

Field	Type	Required	Description
email	string	Yes	User’s email address
password	string	Yes	User’s password

Request Example

curl -X POST "https://api.veriglob.com/internal/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password"
  }'

Response

200 OK

{
  "status": "success",
  "message": "Login successful",
  "data": {
    "user_id": "user_abc123def456",
    "email": "user@example.com",
    "name": "User Name",
    "tier": "basic",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-15T22:30:00Z"
  }
}

Error Responses

Status	Description
400	Invalid request body
401	Invalid email or password

---

User Logout

Invalidates the current session token.

POST /internal/v1/auth/logout

Authentication

Requires InternalSecret.

Request Body

Field	Type	Required	Description
token	string	Yes	The session token to invalidate

Request Example

curl -X POST "https://api.veriglob.com/internal/v1/auth/logout" \
  -H "X-Internal-Secret: your-internal-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response

200 OK

{
  "status": "success",
  "message": "Logout successful",
  "data": {
    "logged_out_at": "2024-01-15T14:30:00Z"
  }
}

Error Responses

Status	Description
400	Invalid or missing token

---

Refresh Token

Refreshes an existing session token.

POST /internal/v1/auth/refresh

Authentication

Requires InternalSecret.

Request Body

Field	Type	Required	Description
refresh_token	string	Yes	The refresh token

Request Example

curl -X POST "https://api.veriglob.com/internal/v1/auth/refresh" \
  -H "X-Internal-Secret: your-internal-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response

200 OK

{
  "status": "success",
  "message": "Token refreshed successfully",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-16T10:30:00Z"
  }
}

Error Responses

Status	Description
400	Invalid request body
401	Invalid or expired refresh token

---

Get Current User

Returns the details of the currently authenticated user.

GET /internal/v1/auth/me

Authentication

Requires InternalSecret and Authorization header with Bearer token.

Request Example

curl -X GET "https://api.veriglob.com/internal/v1/auth/me" \
  -H "X-Internal-Secret: your-internal-secret" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

200 OK

{
  "status": "success",
  "message": "User retrieved successfully",
  "data": {
    "user_id": "user_abc123def456",
    "email": "user@example.com",
    "name": "User Name",
    "tier": "basic",
    "created_at": "2024-01-01T00:00:00Z",
    "last_login_at": "2024-01-15T10:30:00Z"
  }
}

Error Responses

Status	Description
401	Invalid or expired token

---

Session Token Details

Token Structure

Session tokens are JWTs containing:

Claim	Description
sub	User ID
email	User’s email
tier	Subscription tier
iat	Issued at timestamp
exp	Expiration timestamp

Token Expiration

Token Type	Default Expiration
Access Token	12 hours
Refresh Token	30 days

Security Best Practices

1. Store tokens securely - Use secure storage mechanisms (HttpOnly cookies, secure storage APIs)
2. Implement token refresh - Refresh tokens before expiration to maintain session
3. Handle token revocation - Logout users and clear tokens when session ends
4. Use HTTPS only - Never transmit tokens over unencrypted connections