Authenticate API v1.1 requests

Request an OAuth 2.0 access token and use it to authenticate server-side API v1.1 requests.

The API v1.1 base URL is https://api.cloudnumbering.com/v1.1.

Before you start

Create API client credentials in the cloudnumbering portal. Copy the client secret when it is shown and store it in a secrets manager.

Do not put a client secret or access token in browser code, source control, logs or a URL you control.

Request an access token

Read the client ID and client secret into environment variables without writing the values to shell history.

read -r -p 'Client ID: ' CLOUDNUMBERING_CLIENT_ID
read -r -s -p 'Client secret: ' CLOUDNUMBERING_CLIENT_SECRET
printf '\n'
export CLOUDNUMBERING_CLIENT_ID CLOUDNUMBERING_CLIENT_SECRET

Request a token with the client credentials grant.
```
curl --silent --show-error \
  --request POST \
  --url-query 'grant_type=client_credentials' \
  --url-query "client_id=$CLOUDNUMBERING_CLIENT_ID" \
  --url-query "client_secret=$CLOUDNUMBERING_CLIENT_SECRET" \
  'https://api.cloudnumbering.com/v1.1/oauth/token'
```
The token endpoint requires credentials as query parameters. Run this example only on a trusted system, and configure clients, proxies and monitoring tools to redact query strings.

A successful response includes access_token, token_type and expires_in. API v1.1 also returns camelCase compatibility fields. New integrations should use the snake_case OAuth field names.

Read the returned access token into an environment variable without writing it to shell history.

read -r -s -p 'Access token: ' CLOUDNUMBERING_ACCESS_TOKEN
printf '\n'
export CLOUDNUMBERING_ACCESS_TOKEN

Authenticate a request

Send the access token in the Authorization header:

curl --silent --show-error \
  --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
  'https://api.cloudnumbering.com/v1.1/catalogue'

Keep token requests and authenticated API calls on a trusted server. Do not send a cloudnumbering access token to your frontend or another service that does not need it.

Renew an access token

Use expires_in from the token response to track when the access token expires. Read it at runtime rather than hard-coding a lifetime, which can change.

The token response also includes a refresh_token. It is short-lived and its lifetime is not reported in the response. Read it into an environment variable the same way as the other credentials, then exchange it at the token endpoint:

read -r -s -p 'Refresh token: ' CLOUDNUMBERING_REFRESH_TOKEN
printf '\n'

curl --silent --show-error \
  --request POST \
  --url-query 'grant_type=refresh_token' \
  --url-query "client_id=$CLOUDNUMBERING_CLIENT_ID" \
  --url-query "client_secret=$CLOUDNUMBERING_CLIENT_SECRET" \
  --url-query "refresh_token=$CLOUDNUMBERING_REFRESH_TOKEN" \
  'https://api.cloudnumbering.com/v1.1/oauth/token'

Treat a refresh token as a credential with the same care as the client secret. When a refresh request fails for any reason, request a new access token with grant_type=client_credentials rather than retrying the refresh. Your integration should be able to re-authenticate from client credentials at any point.

Handle authentication failures

Token requests and authentication-middleware failures use an OAuth-style error body:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

This differs from the success and error envelope used by most other API endpoints. An invalid, missing or expired bearer token normally returns 401 with error set to invalid_token.

Do not retry invalid_client with the same credentials. Check that the client is active and that the secret is correct. If the secret is unavailable or may be compromised, create replacement credentials in the portal.

Before you start

Request an access token

Authenticate a request

Renew an access token

Handle authentication failures

Next steps