Getting Started with Declytic Auth

Tenants provide isolated authentication contexts for your application. Each tenant can have its own users, roles, and settings.

Machine-to-Machine (M2M) clients authenticate your backend server to the Declytic Auth API using OAuth2 client credentials flow.

Magic links provide passwordless authentication via email. Here's how the flow works:

Step 3.1: Start Magic Link Flow

Send a POST request to initiate the magic link:

POST https://api.auth.declytic.com/v1/auth/magic-link/start

{
  "email": "user@example.com",
  "projectId": "your-tenant-id",
  "redirectUrl": "https://yourapp.com/auth/callback"
}

projectId is your tenant ID from the dashboard. When you send it, redirectUrl must be on that tenant's redirect URI allowlist. The user receives an email with a magic link. When they click it, they're redirected to your redirectUrl with a verification token.

Step 3.2: Verify the Token

Exchange the verification token for an access token:

POST https://api.auth.declytic.com/v1/auth/magic-link/verify

{
  "token": "verification-token-from-email-link"
}

Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "V1StGXR8_Z5jdHi6B-myT",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Verify incoming tokens using the JSON Web Key Set (JWKS) endpoint:

Example validation (using a JWT library):

// Node.js example with jsonwebtoken and jwks-rsa
import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: 'https://api.auth.declytic.com/.well-known/jwks.json'
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

jwt.verify(token, getKey, {
  audience: 'your-tenant-id',
  issuer: 'https://api.auth.declytic.com'
}, (err, decoded) => {
  if (err) {
    // Invalid token
  } else {
    // Token is valid, decoded contains claims
    console.log(decoded.sub); // user ID
    console.log(decoded.email);
  }
});

The issuer is the API origin of the environment that issued the token: Production tokens carry https://api.auth.declytic.com, and Development tokens carry https://api.dev.auth.declytic.com. Verify them against the Development JWKS endpoint, https://api.dev.auth.declytic.com/.well-known/jwks.json.

Use M2M credentials for backend API calls that don't involve a human user:

POST https://api.auth.declytic.com/oauth/token

Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your-m2m-client-id",
  "client_secret": "your-m2m-client-secret",
  "scope": "members:read tenants:read"
}

Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "members:read tenants:read"
}

scope is optional: a space-separated list that narrows the token to some of the scopes the client was granted. Leave it out to receive all of them. The response's scope lists what was granted, and is omitted when the client holds no scopes. The token is always scoped to the client's own tenant.

Use the access_token in the Authorization: Bearer header for API requests.