Generate OAuth Bearer Token

This request generates a token for the partner upon request.

post	/oauth/token

Sample

A sample POST request to generate an OAuth bearer token for a partner:

Unlike most CarrierX API requests, this request must be sent with Content-Type: application/x-www-form-urlencoded, not application/json.

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'grant_type=password&client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c&username=carrierx_partner&password=qwerty123'

Response

200 status code with a serialized copy of the OAuth Token object:

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2024-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2124-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2124-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "test_token",
    "partner_login_sid": null,
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "status": "active",
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}

MFA-gated login

If the OAuth Client (client_id) used for this request has mfa_required set to true and the authenticating Partner Login has an MFA configuration, the response instead comes back with status set to pending_mfa:

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2024-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2124-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2124-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "N/A",
    "partner_login_sid": "7d2a7af0-1b61-48d9-9fc8-35149e42836a",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "partners.read"
    ],
    "status": "pending_mfa",
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}

Note that scopes still lists the login's assigned scopes as normal — they are not emptied in this response. The restriction to MFA verification only is enforced separately, at the authorization layer.

A pending_mfa token is only accepted by Verify MFA Code — it cannot be used for any other request until the MFA code is verified and its status changes to active.

Required Scopes

To generate an OAuth token the partner must have one of the following scopes enabled:

• oauth.manage_all_tokens
• oauth.manage
• oauth.create

Body Arguments

Parameter	Data Type	Description
access_token_expires_in	integer	The access token expiration in seconds.
client_id required	string	The OAuth client ID, used together with the client secret to authenticate this request. Contact CarrierX support at [email protected] to obtain your client ID and client secret.
client_secret required	string	The OAuth client secret, used together with the client ID to authenticate this request. Contact CarrierX support at [email protected] to obtain your client ID and client secret.
grant_type required	string	The grant type for the token. Values accepted in this field are: password to generate and access token. refresh_token to refresh an access or refresh token, or create a new access token without the use of credentials.
name	string	The friendly name used to identify the token.
password \*	string	The password of the partner (used with grant_type = password).
refresh_token \*\*	string	The refresh token (used with grant_type = refresh_token).
refresh_token_expires_in	integer	The refresh token expiration in seconds.
refresh_token_type	string	The type of request (used with grant_type = refresh_token). Values accepted in this field are: access_token to refresh the time during which the access token remains valid. new_token to create a new access token without the use of login and password. refresh_token to refresh the time during which the refresh token remains valid. The default value is access_token.
scope	string	The list of comma-separated partner scopes available for the generated token.
username \*	string	The login of the partner (used with grant_type = password).

*These fields are required if the grant_type attribute is set to password.

**This field is required if the grant_type attribute is set to refresh_token.