Skip to content
English - United Kingdom
  • There are no suggestions because the search field is empty.

How do I make my first API request?

Exchange your App Integration credentials for an access token, make a call, and confirm the connection works. This article covers everything you need to authenticate against the SpeakUp Public API.

You need an App Integration first. If you do not have one, see how do I create an App Integration and get API credentials?

On this page: What you need · Request an access token · Make your first call · Token expiry · Common problems

What you need

Three values, all shown on the App Integration detail page. To reach it, go to Settings > System > Configuration > API and click the integration name.

Value What it is
Client ID Identifies the integration.
Client Secret Authenticates the integration. Treat it like a password.
Token Endpoint The URL you call to obtain a token. This is specific to your organisation, so take it from the detail page rather than from any example.

You also need the API base URL for your organisation, shown on the same page under API Endpoint Configuration. Throughout the reference articles this appears as {API_BASE_URL}.

Request an access token

SpeakUp uses the OAuth 2.0 client credentials flow. Your system authenticates as itself, with no user login involved.

The detail page shows a ready-to-use cURL command for this request. Copy it and replace <client_secret> with your client secret. It takes this form:

curl -X POST '<TOKEN_ENDPOINT>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'client_secret=<CLIENT_SECRET>'

A successful response returns a token valid for 1 hour:

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Make your first call

Send the token on every request in the Authorization header:

Authorization: Bearer <ACCESS_TOKEN>

Retrieving a list of Issues is the simplest way to confirm the connection works, because it needs only read access:

curl -X GET '{API_BASE_URL}/v1/public/issues' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

A successful response returns your Issues as JSON. If your organisation has none yet, an empty result is still a successful connection.

From here, see Retrieving Issues for filtering, pagination, and the full response structure.

Token expiry

Access tokens are valid for 1 hour, or 3600 seconds. When a token expires, requests using it are rejected.

Your application must request a new token when the current one expires. Do not store a single token permanently, and do not hard-code one into your integration.

The client ID and client secret do not expire. They remain valid until the App Integration is deleted.

Common problems

What you see What it means What to do
The token request is rejected The client ID or client secret does not match. Reopen the detail page and copy both values again. Check that no whitespace was included.
The token request does not reach anything The token endpoint is wrong. It is specific to your organisation. Take it from the App Integration detail page rather than from documentation or another environment.
TokenExpiredError The access token is older than 1 hour. Request a new token. Build token refresh into your integration.
FeatureNotEnabledError The Public API package is not enabled for your organisation. Contact your Customer Success Manager.
ForbiddenError on a request that should work The integration was created with a lower access level than the request needs. Check the access levels on the detail page. Updating Issues requires full access for Issues.

Next steps