Authentication

The AMS API uses two different authentication methods depending on which API version you are using. Make sure you understand which version your integration needs before you begin.

v1 — Basic Auth

All v1 endpoints use HTTP Basic Auth. Pass your AMS username and password as an Authorization header on every request. No session management is required.

💡

Basic Auth credentials are sent on every request. Always use HTTPS.

curl -X POST \
  'https://{amsServer}/{amsAppName}/api/v1/userauthentication?informat=json&format=json' \
  --user username:password \
  -H 'X-APP-ID: your-app-identifier' \
  -H 'Content-Type: application/json' \
  -d '{"username": "your.username", "password": "your.password"}'

We recommend calling this endpoint first to confirm your credentials and permissions are set up correctly before building further.

v2 and v3 — Session-based Auth

V2 and v3 endpoints require a two-step process before you can make any calls. You must complete both steps in order.

Step 1 — Get a Session ID

Call POST /api/v2/application/getApplicationDescription to obtain a session token. The session-header value returned in the response headers is what you need for Step 2.

curl -X POST \
  'https://{amsServer}/{amsAppName}/api/v2/application/getApplicationDescription' \
  -H 'X-APP-ID: your-app-identifier' \
  -H 'Content-Type: application/json' \
  -d '{"appName": "{amsAppName}", "currentDateOnClient": "30-04-2026 09:00"}'

Capture the session-header value from the response headers — you'll need it in Step 2.

Step 2 — Authenticate the User

Call POST /api/v2/user/loginUser using the session token from Step 1.

curl -X POST \
  'https://{amsServer}/{amsAppName}/api/v2/user/loginUser' \
  -H 'session-header: {your-session-token}' \
  -H 'Cookie: JSESSIONID={your-session-token}' \
  -H 'X-APP-ID: your-app-identifier' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "your.username",
    "password": "your.password",
    "loginProperties": {
      "appName": "{amsAppName}",
      "clientTime": "2026-04-30T09:00"
    }
  }'

The response includes an applicationId and a skypeName value. Store both — applicationId is required for some v2 write operations, and skypeName is used as a session token for file uploads.

All subsequent v2/v3 calls

Pass these two headers on every v2 and v3 request:

💡

Sessions expire after a period of inactivity. If you receive authentication errors on subsequent calls, repeat Steps 1 and 2 to obtain a fresh session token.

Before You Begin

Regardless of which API version you use, make sure:

• Your account has Coach access to all users you need to work with
• Your account has Read and Write access to all forms you need
• If your AMS instance enforces MFA, SSO, or Terms Documents, your account must be exempted by an administrator before it can use the API

X-APP-ID Header

All requests should include an X-APP-ID header with a unique identifier for your application (e.g. mycompany.ams.integration). This helps Teamworks support staff identify your requests if you need assistance. It is optional but strongly recommended.