Getting Started

Authentication Setup

Authentication is split between browser or session flows and service-auth flows. The sections below map to mounted routes and the headers the backend reads.

Auth modes mounted by the backend

Mode	Route family	Use it for
Email and password plus JWT	`/auth/signup`, `/auth/login`, `/auth/refresh`	Browser users and test accounts.
API keys	`/org/api-keys`	Server-to-server and CI callers.
MFA completion	`/auth/mfa/complete`	Finishing a password login after MFA.
SSO	`/sso/saml/{provider_id}/login` and `/sso/oidc/{provider_id}/login`	Organization-managed identity.
OAuth browser flow	`/oauth/authorize`	Third-party app authorization.
SCIM	`/scim/v2/*`	Directory provisioning.

Email and password flow

BASH

curl -X POST https://api.memorysync.io/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "correct horse battery staple",
    "organization_name": "Docs Demo Org",
    "full_name": "Docs Demo"
  }'

curl -X POST https://api.memorysync.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "correct horse battery staple"
  }'

Create and use an API key

1Authenticate as a user with org access.
2Create a key with POST /org/api-keys. The payload supports name, environment, optional scopes, and optional project_id.
3Send the raw key later in the X-API-Key header.
4If the key has project_id, project enforcement can reuse it automatically on project-scoped routes.

BASH

curl -X POST https://api.memorysync.io/org/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docs-quickstart",
    "environment": "development",
    "project_id": "prj_demo"
  }'

Headers that change request scope

Header	Used by	Verified behaviour
`Authorization: Bearer ...`	JWT-backed routes	Preferred header for browser or session auth.
`X-API-Key`	Service-auth routes	Primary service-auth header.
`X-Project-ID`	Project-scoped routes	Required unless the API key already pins the project.
`X-End-User-ID`	API-key memory calls	Required for memory calls when one key represents many humans.
`X-Tenant-ID`	Tenant switching	Validated against memberships before request state is updated.

SSO, OAuth, and SCIM entry points

SAML sign-in starts at /sso/saml/{provider_id}/login and posts back to /sso/saml/{provider_id}/acs.
OIDC sign-in starts at /sso/oidc/{provider_id}/login.
OAuth browser authorization starts at GET /oauth/authorize.
SCIM is mounted at /scim/v2.

Auth modes mounted by the backend

Email and password flow

Create and use an API key

Headers that change request scope

SSO, OAuth, and SCIM entry points

Refresh and logout