Authentication Service API

Overview

The Authentication Service manages user authentication, authorization, and session management for Macro. It provides multiple authentication methods including password-based login, passwordless email links, OAuth (Google, Apple, GitHub), and SSO. Base URL: / Authentication: Most endpoints are public (login, signup). Protected endpoints require JWT authentication.

Core Concepts

Authentication Methods

The service supports multiple authentication flows:

Password login - Traditional email/password
Passwordless - Magic link sent via email
OAuth - Google, Apple, GitHub
SSO - SAML-based enterprise SSO

JWT Tokens

Authentication results in two tokens:

Access Token - Short-lived (1 hour), used for API requests
Refresh Token - Long-lived (30 days), used to obtain new access tokens

Both are returned as HTTP-only cookies and in response body.

User Linking

Users can link multiple authentication methods (e.g., password + Google) to the same account.

POST /login/password

Authenticates a user with email and password.

string

required

User email address

password

string

required

User password

access_token

string

JWT access token (1 hour expiry)

refresh_token

string

JWT refresh token (30 day expiry)

Emails are automatically converted to lowercase. If the user exists but isn’t registered in the tenant, they are automatically registered.

{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}

POST /login/passwordless

Sends a magic link to the user’s email for passwordless authentication.

string

required

User email address

redirect_url

string

URL to redirect to after successful authentication

status

string

Status: email_sent

This endpoint is rate-limited to prevent abuse. Maximum 3 requests per IP per 5 minutes.

{
  "email": "[email protected]",
  "redirect_url": "https://app.macro.com/dashboard"
}

POST /login/apple

Authenticates using Apple Sign In.

id_token

string

required

Apple ID token from Sign in with Apple

authorization_code

string

required

Apple authorization code

GET /login/sso

Initiates SAML SSO login flow.

org_id

string

required

Organization ID for SSO

redirect_url

string

Post-login redirect URL

OAuth

Google OAuth

GET /oauth/google

Initiates Google OAuth flow. Redirects to Google’s OAuth consent page.

redirect_url

string

URL to return to after OAuth completes

Google OAuth Callback

GET /oauth/google/callback

Handles the OAuth callback from Google (called automatically after user consent).

code

string

required

Authorization code from Google

state

string

required

State parameter for CSRF protection

User Management

Create User

POST /user

Creates a new user account.

string

required

User email address

password

string

required

User password (minimum 8 characters)

name

string

User’s full name

user_id

string

Created user ID

verification_email_sent

boolean

Whether verification email was sent

Get User Info

GET /user/me

Requires authentication Retrieves information about the authenticated user.

user_id

string

User ID (format: macro|[email protected])

string

User email

name

string

User’s full name

email_verified

boolean

Whether email is verified

organization_id

string

Organization ID (if user is in an org)

created_at

datetime

Account creation timestamp

Update User Name

PUT /user/name

Requires authentication Updates the user’s display name.

name

string

required

New display name

Get User Name

GET /user/name

Requires authentication Retrieves the user’s current display name.

Delete User

DELETE /user/me

Requires authentication Deletes the user’s account and all associated data.

This operation is irreversible. All user data including documents, emails, and messages will be permanently deleted.

Get User Quota

GET /user/quota

Requires authentication Retrieves the user’s current usage quota and limits.

documents

object

Document quota (current count and limit)

storage_bytes

object

Storage quota (current usage and limit)

api_calls

object

API call quota for current period

Update User Tutorial Status

PATCH /user/tutorial

Requires authentication Marks tutorial steps as completed.

tutorial_step

string

required

Tutorial step identifier

completed

boolean

required

Whether the step is completed

PATCH /user/ai_consent

Requires authentication Updates the user’s AI feature consent preferences.

consented

boolean

required

Whether user consents to AI features

JWT & Session Management

Refresh Access Token

POST /jwt/refresh

Exchanges a refresh token for a new access token.

refresh_token

string

required

Current refresh token

access_token

string

New access token

The refresh token is also renewed and returned. Old tokens are invalidated.

Generate Macro API Token

POST /jwt/macro_api_token

Requires authentication Generates a long-lived API token for programmatic access.

api_token

string

API token (valid for 1 year)

expires_at

datetime

Token expiration time

Logout

POST /logout

Requires authentication Invalidates the current session and tokens.

Account Linking

Create GitHub Link

POST /link/github

Requires authentication Initiates GitHub account linking flow.

redirect_url

string

URL to redirect after linking completes

Remove Account Link

DELETE /link/{provider}

Requires authentication Removes a linked authentication provider.

provider

string

required

Provider to unlink: google, apple, github

Check Link Exists

GET /user/link_exists

Requires authentication Checks if user has linked a specific provider.

provider

string

required

Provider to check: google, apple, github, gmail

exists

boolean

Whether the link exists

Permissions

Get User Permissions

GET /permissions

Requires authentication Retrieves the user’s permissions and feature flags.

permissions

array

Array of permission strings

features

object

Feature flags and their enabled status

Get Legacy User Permissions

GET /user/legacy_user_permissions

Requires authentication Retrieves user permissions in legacy format (for backwards compatibility).

Teams & Organizations

Get User Organization

GET /user/organization

Requires authentication Retrieves information about the user’s organization.

string

Organization ID

name

string

Organization name

role

string

User’s role in the organization

Update User Group

PATCH /user/group

Requires authentication Updates the user’s group membership within their organization.

group_id

string

required

New group ID

Error Codes

Common Errors

200 - Success
201 - Created
400 - Bad Request (invalid email, weak password)
401 - Unauthorized (invalid credentials)
403 - Forbidden (email not verified, account locked)
404 - User not found
429 - Too Many Requests (rate limited)
500 - Internal Server Error

Service-Specific Error Codes

message

string

Human-readable error description

Authentication Errors:

INVALID_CREDENTIALS - Email/password combination is incorrect
EMAIL_NOT_VERIFIED - User hasn’t verified their email address
ACCOUNT_LOCKED - Account has been locked due to security concerns
TOKEN_EXPIRED - JWT token has expired
TOKEN_INVALID - JWT token is malformed or invalid
RATE_LIMIT_EXCEEDED - Too many login attempts

Registration Errors:

EMAIL_IN_USE - Email already registered
WEAK_PASSWORD - Password doesn’t meet complexity requirements
INVALID_EMAIL - Email format is invalid

{
  "message": "unable to login user"
}

Data Models

User

interface User {
  user_id: string;              // Format: "macro|[email protected]"
  email: string;
  name?: string;
  email_verified: boolean;
  organization_id?: string;
  created_at: string;
  updated_at: string;
}

User Tokens Response

interface UserTokensResponse {
  access_token: string;         // JWT, 1 hour expiry
  refresh_token: string;        // JWT, 30 day expiry
}

User Quota

interface UserQuota {
  documents: QuotaInfo;
  storage_bytes: QuotaInfo;
  api_calls: QuotaInfo;
}

interface QuotaInfo {
  current: number;
  limit: number;
  reset_at?: string;            // For time-based quotas
}

Permissions

interface UserPermissions {
  permissions: string[];        // e.g., ["read:documents", "write:documents"]
  features: {
    [key: string]: boolean;     // Feature flag map
  };
}

Organization

interface Organization {
  id: string;
  name: string;
  created_at: string;
  subscription_tier: "free" | "pro" | "enterprise";
}

Overview

Core Services

Processing Services

​Overview

​Core Concepts

​Authentication Methods

​JWT Tokens

​User Linking

​Login

​Password Login

​Passwordless Login

​Apple Login

​SSO Login

​OAuth

​Google OAuth

​Google OAuth Callback

​User Management

​Create User

​Get User Info

​Update User Name

​Get User Name

​Delete User

​Get User Quota

​Update User Tutorial Status

​Update AI Consent

​JWT & Session Management

​Refresh Access Token

​Generate Macro API Token

​Logout

​Account Linking

​Create GitHub Link

​Remove Account Link

​Check Link Exists

​Permissions

​Get User Permissions

​Get Legacy User Permissions

​Teams & Organizations

​Get User Organization

​Update User Group

​Error Codes

​Common Errors

​Service-Specific Error Codes

​Data Models

​User

​User Tokens Response

​User Quota

​Permissions

​Organization

Build docs developers (and LLMs) love

Overview

Core Concepts

Authentication Methods

JWT Tokens

User Linking

Login

Password Login

Passwordless Login

Apple Login

SSO Login

OAuth

Google OAuth

Google OAuth Callback

User Management

Create User

Get User Info

Update User Name

Get User Name

Delete User

Get User Quota

Update User Tutorial Status

Update AI Consent

JWT & Session Management

Refresh Access Token

Generate Macro API Token

Logout

Account Linking

Create GitHub Link

Remove Account Link

Check Link Exists

Permissions

Get User Permissions

Get Legacy User Permissions

Teams & Organizations

Get User Organization

Update User Group

Error Codes

Common Errors

Service-Specific Error Codes

Data Models

User

User Tokens Response

User Quota

Permissions

Organization