Authentication

Every GAINS Connect endpoint except GET /ping needs credentials in the Authorization header. GET /ping ignores any credentials you send. This page explains the two schemes GAINS Connect accepts, how to get a token, and what the API answers when credentials are missing or refused.

Choose a scheme

Scheme	Credentials	Use it for
Basic	The user name and password of a GAINS user	All endpoints except partner endpoints
Bearer (OAuth 2.0)	A client ID and secret, exchanged for a short-lived access token	All endpoints, and required for partner endpoints such as `POST /partners/vendor-parameters`

Ask your GAINS representative for either set of credentials. For Basic, a GAINS administrator creates the user in GAINS User Management; use a dedicated user for your integration rather than a person's account.

Basic authentication

Send the user name and password, joined by a colon and Base64-encoded, on every request.

curl https://acme.gainsystems.com/api/v1/customers \
  -u "integration.user:<password>"

Bearer authentication

Request a token

Send a POST to the token endpoint of the GAINS authorization server with an application/x-www-form-urlencoded body.

Environment	Token endpoint
Production	`https://auth.gainsapps.com/realms/GAINSystems/protocol/openid-connect/token`
Development	`https://auth-dev.gainsapps.com/realms/GAINSystems/protocol/openid-connect/token`

These servers issue tokens only. They are the same for every customer and are not your GAINS Connect environment.

Field	Value
`grant_type`	`client_credentials`
`client_id`	The client ID you were issued
`client_secret`	The client secret you were issued

curl -X POST https://auth.gainsapps.com/realms/GAINSystems/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<your client id>" \
  -d "client_secret=<your client secret>"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...",
  "expires_in": 600,
  "token_type": "Bearer"
}

Field	Meaning
`access_token`	The token to send to GAINS Connect.
`expires_in`	Seconds until the token expires.
`token_type`	Always `Bearer`.

Use the token

Send the access_token on every request.

curl https://acme.gainsystems.com/api/v1/customers \
  -H "Authorization: Bearer <access_token>"

Reuse a token until shortly before expires_in runs out, then request a new one with the same client credentials. Requesting a token for every call is unnecessary.

What a token grants

A token is valid only for the GAINS Connect environment it was issued for. Your client is granted access to groups of endpoints, for example loading master data or reading replenishment orders. A token without access to an endpoint gets 403. Ask your GAINS representative to change what your client can call.

When authentication fails

Errors use the standard error body; see Errors Handling & Exceptions.

Status	`Reason`	What to do
`401`	`The token is invalid or has expired. Please request a new token.`	Credentials are missing, or the token is invalid or expired. Request a new token.
`401`	`The credentials provided are not valid.`	GAINS refused the Basic user name or password. Check them.
`401`	`This endpoint accepts Bearer tokens only.`	Basic credentials were sent to a partner endpoint. Send a Bearer token.
`403`	`The token used has not been granted scope for this route.`	The token is valid but not for this endpoint. Ask your GAINS representative for access.
`503`	`Authentication service is currently unavailable. Please try again later.`	GAINS could not be reached to check Basic credentials. Retry later.

{
  "Reason": "The token is invalid or has expired. Please request a new token."
}