Skip to main content
The Frontend API (also known as the Public API) is the main interface for client applications to interact with Ory Kratos. It provides endpoints for:
  • Session management and authentication
  • Self-service flows (login, registration, recovery, verification, settings)
  • Error handling

​
Base URL

The Frontend API is available at your Ory Kratos public URL: 
https://your-project.projects.oryapis.com
For self-hosted instances, this is typically: 
http://localhost:4433

​
Authentication

The Frontend API uses session-based authentication with two methods: For browser applications, Ory Kratos automatically manages sessions using HTTP cookies. After a successful login, Kratos sets a session cookie that’s automatically sent with subsequent requests. 
curl -X GET 'https://your-project.projects.oryapis.com/sessions/whoami' \
  -H 'Cookie: ory_kratos_session=...' \
  -H 'Content-Type: application/json'

​
Token-based authentication

For native mobile apps and non-browser clients, use session tokens in the X-Session-Token header: 
curl -X GET 'https://your-project.projects.oryapis.com/sessions/whoami' \
  -H 'X-Session-Token: MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj' \
  -H 'Content-Type: application/json'
Session tokens are returned in the session_token field when completing API flows (non-browser flows). When integrating Ory Kratos with your application:

​
Browser applications

  • Kratos automatically sets and manages session cookies
  • Ensure your application’s domain allows cookies from the Kratos domain
  • Configure CORS properly to allow credentials

​
Server-side proxies

If you’re calling Kratos from a backend server on behalf of users:
  • Forward the Cookie header from the client’s request to Kratos
  • Return the Set-Cookie header from Kratos back to the client
router.get('/api/whoami', async (req, res) => {
  const response = await fetch('https://your-kratos-url/sessions/whoami', {
    headers: {
      'Cookie': req.headers.cookie
    }
  });
  
  // Forward Set-Cookie headers back to client
  const setCookie = response.headers.get('set-cookie');
  if (setCookie) {
    res.setHeader('Set-Cookie', setCookie);
  }
  
  const session = await response.json();
  res.json(session);
});

​
Integration patterns

​
Single-page applications (SPA)

For React, Vue, Angular, or other SPAs:
  1. Use cookie-based authentication
  2. Configure CORS to allow credentials from your SPA domain
  3. Use credentials: 'include' in fetch requests
const session = await fetch('https://your-kratos-url/sessions/whoami', {
  credentials: 'include'
});

​
Mobile applications

For iOS, Android, or other native apps:
  1. Use token-based authentication
  2. Store the session token securely (keychain/keystore)
  3. Include the token in the X-Session-Token header
var request = URLRequest(url: url)
request.setValue(sessionToken, forHTTPHeaderField: "X-Session-Token")

​
Server-side applications

For traditional server-rendered apps:
  1. Use cookie-based authentication
  2. Forward cookies between your server and Kratos
  3. Implement middleware to check session status

​
Rate limiting

Frontend API endpoints are rate-limited based on different buckets:
  • kratos-public-low: Sensitive operations (1000 requests/minute)
  • kratos-public-medium: Regular operations (2000 requests/minute)
  • kratos-public-high: High-frequency operations (5000 requests/minute)
Rate limit information is included in response headers:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Time when the limit resets

​
Error handling

The Frontend API returns errors in a consistent JSON format: 
{
  "error": {
    "id": "string",
    "code": 404,
    "status": "Not Found",
    "message": "The resource could not be found",
    "reason": "User with ID 1234 does not exist."
  }
}
For self-service flow errors, use the error endpoint to retrieve user-friendly error details.

​
Next steps

Session management

Manage user sessions and authentication

Error handling

Retrieve and display flow errors

Build docs developers (and LLMs) love

Get started for freeTalk to us