> ## Documentation Index
> Fetch the complete documentation index at: https://developers.momogood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Session-cookie login flow, optional OTP, and per-namespace authorization rules.

All endpoints require an authenticated EMS user session. The session is established via the EMS login flow on the same regional hostname (see [Base URL and regions](/events-auctions/base-url-and-regions)) and is represented as an HTTP cookie. Every subsequent request must echo that cookie back.

<Info>
  **Coming Soon — OAuth 2.0 and API-key authentication.** Today the API uses the session-cookie flow described below. Contact [support@givergy.com](mailto:support@givergy.com) to be notified when OAuth or API-key auth becomes available.
</Info>

## Step 1 — Log in

```http theme={null}
POST {EMS_BASE_URL}/checkin/v1/auth/login
Content-Type: application/json

{
  "username": "<your-username>",
  "password": "<your-password>",
  "version": 0
}
```

A successful response sets a session access cookie and, in most deployments, an `X-CSRF-Token` response header. Send the cookie on every subsequent request.

If your integration submits non-`GET` requests (none of the endpoints documented here do), also echo the CSRF token back as `X-CSRF-Token`.

## Optional — OTP / multi-factor

If your account requires OTP for sign-in, exchange these requests before calling the data endpoints:

```http theme={null}
POST {EMS_BASE_URL}/checkin/v1/auth/otp-login/requestCode
POST {EMS_BASE_URL}/checkin/v1/auth/otp-login/checkCode
```

`requestCode` triggers OTP delivery (SMS or email per the user's MFA settings). `checkCode` verifies the supplied code and upgrades the session to fully authenticated.

## Step 2 — Authorization rules per family

All endpoints share session authentication but apply **different authorization checks** per family:

| Family             | Path prefix            | Authorization                                                                                                                                                                                                 |
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Custom Data Export | `/<your-namespace>/v1` | The authenticated user **must be the dedicated service user** provisioned for your integration. Any other authenticated user receives `403 Forbidden`. The user must also have access to the requested event. |
| Salesforce         | `/salesforce/v1`       | The authenticated user must have access to the requested event. No dedicated-user restriction.                                                                                                                |
| Blackbaud          | `/blackbaud/v1`        | The authenticated user must have access to the requested event. No dedicated-user restriction.                                                                                                                |

<Note>
  Custom Data Export endpoints require a dedicated service user provisioned per customer. If you receive `403 Forbidden` with a body like `{"code":"forbidden","message":"Access forbidden: not a <namespace> client","extra":"<your-user-uuid>"}`, the account you authenticated as is not the configured service user for your integration. Contact [support@givergy.com](mailto:support@givergy.com) to provision the right service user.
</Note>

## Credential handling

Session-cookie authentication ties the integration to a specific service-user account and password. Treat the credentials as you would any other privileged secret:

* Store them in a secret manager, not in source control or environment files committed to a repo.
* Rotate on a schedule and after any suspected compromise.
* Avoid sharing credentials across environments (sandbox vs. production).

## Errors specific to authentication

| Status             | Code           | When you'll see it                                                                                                                                                                                    |
| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | `unauthorized` | Missing or invalid session cookie. Re-run the login flow.                                                                                                                                             |
| `403 Forbidden`    | `forbidden`    | Authenticated but not authorized. For Custom Data Export paths this is usually the dedicated-user check failing. For all paths it can also mean the user does not have access to the requested event. |

See the full [Errors page](/events-auctions/errors) for the complete error shape and other status codes.