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 to track when the access token expires. Token responses currently also include a refresh_token, which is valid for 24 hours from issue; the response does not state that lifetime, so track it yourself. To renew without re-sending stored credentials, read the refresh token 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'

After the refresh token's 24 hours pass, or if a refresh fails, request another access token with grant_type=client_credentials. The reference schema marks refresh_token as optional, so keep the client-credentials path as your fallback rather than assuming a refresh token is always present.

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