Authentication

The Replyco API uses bearer tokens. Your integration signs in with the email address and password of a Replyco user, receives an access token and a refresh token, and sends the access token in the Authorization header of every other call. Each token stands for that one user, and every call works with the data of that user’s company. There are no scopes to request.

Getting credentials

Ask Replyco support to enable the API for your company.
Choose the Replyco user your integration signs in as. The user must be active in your company. Everything the integration does is recorded as that user: a reply sent through the API, for example, shows as that user’s reply. A dedicated user for the integration keeps its actions apart from your agents’ work. The ticket list shows only tickets of the channels and folders that user has access to in Replyco, so give the user access to every channel the integration works with.
Store the user’s email address and password in your system’s secret store. They are the only credentials the API needs.

Requesting a token

Call POST /openapi/auth/token with grantType set to password:

curl -X POST https://open-api.replyco.com/openapi/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grantType": "password", "email": "integration@example.com", "password": "<your-password>"}'

{ "grantType": "password", "email": "integration@example.com", "password": "<your-password>" }

{
  "accessToken": "<access-token>",
  "refreshToken": "<refresh-token>",
  "expiresIn": "2026-10-24T09:15:00Z"
}

Field	Meaning
`accessToken`	The token you send on every other call.
`expiresIn`	The moment the access token expires, in UTC. It is a date and time, not a number of seconds.
`refreshToken`	The token that gets you a new access token without the password.

Using it

Send the access token in the Authorization header with the Bearer prefix:

curl https://open-api.replyco.com/openapi/user/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Every operation except the token operation needs this header. A call without a token, or with one that has expired or is not valid, is refused with 401 and an empty body. The WWW-Authenticate response header says Bearer.

Expiry and refresh

Token	Lifetime
Access token	72 hours from sign-in.
Refresh token	90 days.

Keep the access token and reuse it until shortly before expiresIn. Then call the same operation with grantType set to refresh_token:

{ "grantType": "refresh_token", "refreshToken": "<refresh-token>" }

The answer has the same shape as a sign-in. Store the refreshToken it returns and use it for the next refresh. When a refresh is refused with 400, because the refresh token has expired or the user has been blocked, sign in with the password again.

The token operation accepts at most 3 calls a minute from one IP address (see Rate limits), so an integration that signs in before every call stops working almost at once.

What 400, 401 and 403 mean

Status	Where	Meaning	What to do
400	`POST /openapi/auth/token`	The sign-in or refresh was refused: an empty body, an unknown `grantType`, a wrong email address or password, a user who is not active, or a refresh token that is unknown or expired.	Check the credentials and the `grantType`; for a refused refresh, sign in with the password. Do not retry the same request in a loop.
401	every other operation	The access token is missing, has expired or is not valid.	Refresh the token, or sign in again, and repeat the call once.
403	some operations	The user the token stands for may not do this.	Sign in as a user who may, or ask an administrator of your Replyco company.

Tips

Reuse an access token until shortly before it expires (72 hours), then get a new one with the refresh token instead of signing in with the password again.
Sign in at most 3 times a minute from one IP address; keep the access token and refresh it instead of requesting a new one per call.

Your first request: sign in and make a first call, end to end.
Rate limits: how often you may call the token operation and the rest of the API.
API reference: the token operation’s full request and response.