Authentication

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) and is represented as an HTTP cookie. Every subsequent request must echo that cookie back.

Coming Soon — OAuth 2.0 and API-key authentication. Today the API uses the session-cookie flow described below. Contact support@givergy.com to be notified when OAuth or API-key auth becomes available.

Step 1 — Log in

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:

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.

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 to provision the right service user.

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 for the complete error shape and other status codes.

Overview

Endpoints

Reference

Step 1 — Log in

Optional — OTP / multi-factor

Step 2 — Authorization rules per family

Credential handling

Errors specific to authentication

​Step 1 — Log in

​Optional — OTP / multi-factor

​Step 2 — Authorization rules per family

​Credential handling

​Errors specific to authentication

Step 1 — Log in

Optional — OTP / multi-factor

Step 2 — Authorization rules per family

Credential handling

Errors specific to authentication