Docs: Authentication

Table of Contents

Overview v2.4

This guide explains the authentication mechanisms available for our platform. Choose the method that best fits your application's security requirements.

JSON Web Tokens (JWT)

JWTs are signed tokens that contain user claims. They are stateless and can be verified without a database lookup.

Generating a JWT


const jwt = require('jsonwebtoken');
const payload = { sub: user.id, role: user.role };
const token = jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '1h' });

Verifying a JWT


function verifyToken(token) {
    try {
        return jwt.verify(token, process.env.JWT_SECRET);
    } catch (e) {
        throw new Error('Invalid token');
    }
}

OAuth 2.0 Flow

Our OAuth implementation follows the Authorization Code Grant with PKCE for native apps.

  1. Redirect the user to /oauth/authorize with client_id, redirect_uri, code_challenge, and state.
  2. User logs in and consents.
  3. Authorization server redirects back with code and state.
  4. Exchange code for an access_token at /oauth/token using code_verifier.

Sample Request


POST /oauth/token HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=xyz123&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&code_verifier=abc456&client_id=client123

API Usage

All protected endpoints require the Authorization: Bearer <token> header.


fetch('/api/user/profile', {
    headers: {
        'Authorization': `Bearer ${token}`
    }
})
.then(res => res.json())
.then(data => console.log(data));

Error Handling

Standard error responses: