Exchange V1 API Key for V2 OAuth token

This single endpoint is used to exchange a valid Mailbox API 1.0 API Key for a renewable OAuth token.

Upon a successful request you will be granted a new OAuth token that will also contain a UUID refresh token to be used to refresh the accessToken upon expiry. Subsequent requests with the same V1 API key will not create new tokens, they will just return the already existing token.

Request

POST https://transition.helpscout.net HTTP/1.1
Content-Type: application/json; charset=UTF-8

{
  "apiKey": "6ba12b27cd0d40fdd1d5c0dd9631b74b6b85",
  "clientId": "64881cdbbe64ef893ef4c607d89259e"
}

Request fields

Path Type Description
apiKey String Valid Mailbox API 1.0 API Key
clientId String Valid OAuth Application ID

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "accessToken": "23423",
    "expiresIn": 7200,
    "refreshToken": "2342342"
}

Response fields

Path Type Description
accessToken String Valid OAuth Token for use in interacting with V2 of the API
expiresIn Number Number of seconds until the token must be refreshed
refreshToken String UUID that must be used to refresh the token upon expiry

Error responses

In the event of a bad request the endpoint will respond with the following format and detailing whether the V1 API key is invalid or if the clientId is not valid or doesn’t exist.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
    "status":400,
    "message":"6ba12b27cd0d40fdd1d5c0dd9631b74b6b85 is not a valid API Key"
}