User Authentication

Deprecated

JWT authentication is supported for existing integrations but should not be used for new integrations. New server-to-server integrations should use API Key Authentication.

Use this reference to maintain an existing integration that obtains tokens with an IIMMPACT account username and password.

Obtain tokens

POST https://api.iimmpact.com/v2/token

This endpoint does not require an Authorization header.

Request body

Field	Type	Required	Description
username	string	Yes	IIMMPACT account username
password	string	Yes	IIMMPACT account password

The endpoint accepts application/json and application/x-www-form-urlencoded request bodies.

curl --request POST "https://api.iimmpact.com/v2/token" \
  --header "Content-Type: application/json" \
  --data '{
    "username": "your-username",
    "password": "your-password"
  }'

Successful response

{
  "AuthenticationResult": {
    "AccessToken": "eyJraWQiOi...",
    "ExpiresIn": 3600,
    "TokenType": "Bearer",
    "RefreshToken": "eyJjdHkiOi...",
    "IdToken": "eyJraWQiOi..."
  }
}

Field	Description
AuthenticationResult.IdToken	Token used to authenticate legacy IIMMPACT API requests
AuthenticationResult.AccessToken	Access token; it is not accepted as authentication for IIMMPACT API requests
AuthenticationResult.RefreshToken	Token used with /v2/token/refresh to obtain a new ID token
AuthenticationResult.ExpiresIn	Token lifetime in seconds
AuthenticationResult.TokenType	Token type, normally Bearer

Send the ID token, not the access token, in subsequent legacy API requests:

Authorization: Bearer <AuthenticationResult.IdToken>

Refresh tokens

POST https://api.iimmpact.com/v2/token/refresh

This endpoint does not require an Authorization header.

Request body

Field	Type	Required	Description
refresh_token	string	Yes	Refresh token returned by /v2/token

curl --request POST "https://api.iimmpact.com/v2/token/refresh" \
  --header "Content-Type: application/json" \
  --data '{
    "refresh_token": "your-refresh-token"
  }'

The successful response uses the same AuthenticationResult structure as /v2/token. AuthenticationResult.RefreshToken may be null, so continue using the original refresh token.

Error handling

Missing mandatory fields

A missing username, password, or refresh_token returns HTTP 400 Bad Request with field-level validation errors:

{
  "message": "The given data was invalid.",
  "errors": {
    "username": [
      "The username field is required."
    ]
  }
}

Invalid credentials or token

Invalid credentials, an unknown user, or an invalid refresh token returns HTTP 401 Unauthorized with message and errors fields. The message varies by failure. For example, an incorrect username or password can return:

{
  "message": "Incorrect username or password.",
  "errors": {}
}

Do not automatically retry an invalid username, password, or refresh token. Ask the account owner to verify the credentials or migrate the integration to API Key authentication.

Migration recommendation

API keys are tied to the organization and authenticate requests directly with HMAC-SHA256 signatures. They do not use /v2/token. See API Key Authentication for the required headers, signing algorithm, examples, and authentication error codes.

Keep credentials and tokens in secure server-side storage. Never place them in browser or mobile application code, logs, chat messages, or source control.