Guest Login

Complete guide for implementing guest authentication using Guardian’s /v1/guest/login endpoint.

Overview

Guardian implements guest authentication to allow anonymous or unauthenticated users to access your application with limited permissions. Guest users are identified by a device or app-instance derived identifier, which can optionally be encrypted using AES-CBC encryption for enhanced security.

How It Works

The guest login flow is a single-step process:

Client sends a guest identifier: Client provides a guest identifier (optionally encrypted), client ID, and requested scopes
Guardian validates and processes: Guardian validates the request, decrypts the identifier if encrypted, validates scopes, and generates an access token
Token response: Guardian returns an access token in the response body and as an HTTP-only cookie

Key Features:

Optional Encryption: Guest identifiers can be encrypted using AES-CBC algorithm with a shared secret key
Scope Validation: Scopes are validated against both guest allowed scopes and client scopes
Cookie Support: Access token is automatically set as an HTTP-only cookie for seamless integration
No User Service Required: Guest login does not require user service integration - it works independently

Prerequisites

Before implementing guest authentication, ensure you have:

Guardian Tenant: A configured tenant ID
OAuth Client: A registered client ID for your application
Guest Configuration: Guest configuration set up in the database (encryption settings, allowed scopes)

Configuration

Guest authentication configuration is tenant-specific and stored in the guest_config database table. See Guest Configuration for the complete schema, field descriptions, and encryption details.

API Endpoint

Endpoint: POST /v1/guest/login

Purpose: Authenticates a guest user and returns an access token. The guest identifier can be encrypted or plain text based on tenant configuration.

Headers:

Content-Type: application/json
tenant-id: <your-tenant-id> (required)

Request Body:

{
  "guest_identifier": "QwnZ/2k+mpCm27nFOqb95g==",
  "client_id": "my-client-id",
  "scopes": ["profile", "email", "phone"]
}

Request Parameters:

Parameter	Type	Required	Description
guest_identifier	string	Yes	Device or app-instance derived identifier. Must be encrypted if tenant configuration `is_encrypted` is true, otherwise plain text
client_id	string	Yes	Guardian OAuth client ID. This must be created in Guardian before use
scopes	array[string]	Yes	Array of OAuth scopes to request (e.g., [“profile”, “email”, “phone”])

Response: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

Response Parameters:

Parameter	Type	Description
access_token	string	JWT access token for API authentication
token_type	string	Token type. Always “Bearer”
expires_in	integer	Access token expiration time in seconds

Response Headers:

The access token is also returned as an HttpOnly cookie in the Set-Cookie header:

Set-Cookie: AT=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...; Path=/; HttpOnly; Secure; SameSite=Strict

Error Responses:

Code	Status	Message	When	Resolution
invalid_request	400	guestIdentifier cannot be null or empty	Missing or empty guest_identifier	Provide valid guest_identifier
invalid_request	400	clientId cannot be null or empty	Missing or empty client_id	Provide valid client_id
invalid_request	400	scopes cannot be null or empty	Missing or empty scopes array	Provide at least one scope
invalid_guest_identifier	400	Invalid guest identifier	Decryption failed or invalid encrypted format	Verify encryption/decryption logic and secret key
invalid_scope	400	Invalid scope <scope>	Scope not in guest allowed scopes or client scopes	Use only allowed scopes
client_not_found	404	Client not found	Client ID does not exist	Verify client_id exists in Guardian
client_not_found	404	Client not found	Client ID does not exist for tenant	Verify client_id exists for the specified tenant

API Specification

Request Schema

V1GuestLoginRequestBody

type: object
required:
  - guest_identifier
  - client_id
  - scopes

properties:
  guest_identifier:
    type: string
    description: Device- or app-instance-derived identifier. Must be encrypted if tenant configuration is_encrypted is true, otherwise plain text
    example: "QwnZ/2k+mpCm27nFOqb95g=="

  client_id:
    type: string
    description: Guardian OAuth client ID. This must be created in Guardian before use
    example: "my-client-id"

  scopes:
    type: array
    items:
      type: string
    description: Array of OAuth scopes to request
    example: ["profile", "email", "phone"]

Response Schema

GuestLoginResponse

type: object
properties:
  access_token:
    type: string
    description: JWT access token for API authentication

  token_type:
    type: string
    example: "Bearer"
    description: Token type. Always "Bearer"

  expires_in:
    type: integer
    description: Access token expiration time in seconds

For complete request and response schemas, refer to the Guardian API Specification.

Examples

cURL Examples

Guest Login with Encrypted Identifier:

curl --location 'http://localhost:8080/v1/guest/login' \
--header 'Content-Type: application/json' \
--header 'tenant-id: tenant1' \
--data '{
    "guest_identifier": "QwnZ/2k+mpCm27nFOqb95g==",
    "client_id": "my-client-id",
    "scopes": ["profile", "email", "phone"]
}'

Guest Login with Plain Text Identifier (when is_encrypted is false):

curl --location 'http://localhost:8080/v1/guest/login' \
--header 'Content-Type: application/json' \
--header 'tenant-id: tenant2' \
--data '{
    "guest_identifier": "test123",
    "client_id": "my-client-id",
    "scopes": ["profile"]
}'

Flow Diagram

┌─────────┐                    ┌──────────┐
│ Client  │                    │ Guardian │
│         │                    │          │
└────┬────┘                    └────┬─────┘
     │                              │
     │ 1. POST /v1/guest/login      │
     │─────────────────────────────>│
     │ {guest_identifier,           │
     │  client_id, scopes}          │
     │                              │
     │                              │ 2. Validate request
     │                              │    (guest_identifier, client_id, scopes)
     │                              │
     │                              │ 3. Get guest config
     │                              │    (is_encrypted, secret_key, allowed_scopes)
     │                              │
     │                              │ 4. Decrypt guest_identifier
     │                              │    (if is_encrypted is true)
     │                              │
     │                              │ 5. Validate scopes
     │                              │    - Check against guest allowed_scopes
     │                              │    - Check against client scopes
     │                              │
     │                              │ 6. Generate access token
     │                              │    (JWT with guest_identifier as subject)
     │                              │
     │                              │ 7. Set access token cookie
     │                              │
     │ 8. Return access token       │
     │<─────────────────────────────│
     │ {access_token, token_type,   │
     │  expires_in}                 │
     │ + Set-Cookie header          │
     │                              │

Access Token Details

The access token returned by guest login is a JWT (JSON Web Token) with the following claims:

Claim	Description
`sub`	Guest identifier (decrypted if encryption was used)
`scope`	Space-separated list of granted scopes
`tenant_id`	Tenant identifier
`client_id`	Client ID used for authentication
`exp`	Token expiration timestamp
`iat`	Token issuance timestamp
`amr`	Authentication method reference (empty array for guest login)

Troubleshooting

”Invalid guest identifier” Error

Problem: Request fails with “Invalid guest identifier” error

Possible Causes:

Decryption failed due to incorrect secret key
Encrypted identifier format is invalid (not Base64)
Encryption algorithm or parameters don’t match Guardian’s implementation
Plain text identifier provided when encryption is required

Solutions:

Verify secret_key in guest_config matches the key used for encryption
Ensure encrypted identifier is Base64-encoded
Check that encryption uses AES-CBC with zero IV
Verify padding is correct (plain text must be block-aligned)
If is_encrypted is true, ensure you’re sending encrypted identifier
If is_encrypted is false, ensure you’re sending plain text identifier

”Invalid scope” Error

Problem: Request fails with “Invalid scope” error

Possible Causes:

Requested scope is not in guest allowed_scopes
Requested scope is not assigned to the client
Scope name is misspelled

Solutions:

Check allowed_scopes in guest_config table
Verify client has the requested scopes assigned in client_scope table
Ensure scope names match exactly (case-sensitive)
Use only scopes that are both in guest allowed scopes and client scopes

”Client not found” Error

Problem: Request fails with “Client not found” error

Possible Causes:

Client ID doesn’t exist in Guardian
Client ID belongs to a different tenant
Client ID is misspelled

Solutions:

Verify client exists in client table for the specified tenant
Check that client_id matches exactly (case-sensitive)
Ensure client is created before using it for guest login

”scopes cannot be null or empty” Error

Problem: Request fails with “scopes cannot be null or empty” error

Solutions:

Provide at least one scope in the scopes array
Ensure scopes is not null or empty array
Verify JSON format is correct

Problem: Access token cookie is not being set in browser

Possible Causes:

Cookie settings (domain, path, secure, sameSite) don’t match your application
Browser is blocking cookies
HTTPS is required but using HTTP

Solutions:

Check cookie configuration in token_config table
Verify cookie_domain matches your application domain
Ensure cookie_secure is set appropriately (true for HTTPS, false for HTTP in development)
Check browser console for cookie-related errors
Use HTTPS in production environments

Best Practices

Encryption: Enable encryption for guest identifiers in production to protect user privacy
Secret Key Management: Store secret keys securely and rotate them periodically
Scope Limitation: Limit guest allowed scopes to only what’s necessary for anonymous access
Token Expiration: Set appropriate access token expiration time (default: 900 seconds / 15 minutes)
HTTPS: Use HTTPS for all API calls in production to protect tokens in transit
Cookie Security: Configure secure cookie settings (HttpOnly, Secure, SameSite) appropriately
Identifier Generation: Generate unique, non-guessable guest identifiers for each device/app instance
Scope Validation: Always validate scopes on both client and server side
Error Handling: Implement proper error handling and user feedback for authentication failures
Token Storage: Store tokens securely (HttpOnly cookies or secure storage) and never expose them in client-side code or URLs

Post Authentication - Session management and Logout
Configuration - Guardian configuration options
Guest Configuration - Guest authentication configuration

Guest Login

Overview

How It Works

Prerequisites

Configuration

API Endpoint

Guest Login

API Specification

Request Schema

V1GuestLoginRequestBody

Response Schema

GuestLoginResponse

Examples

cURL Examples

Flow Diagram

Complete Guest Login Flow

Access Token Details

Troubleshooting

”Invalid guest identifier” Error

”Invalid scope” Error

”Client not found” Error

”scopes cannot be null or empty” Error

Access Token Cookie Not Set

Best Practices

Related Documentation