Managing App Integrations
1. Introduction to App Integrations
App Integrations provide secure, machine-to-machine (M2M) access to SpeakUp’s Public APIs using the OAuth 2.0 Client Credentials flow.
An App Integration represents an external system or service (for example, a backend service, integration platform, or partner application). Each App Integration:
-
Has its own credentials (Client ID and Client Secret)
-
Is assigned explicit permissions at creation time
-
Is used only to obtain bearer tokens
Bearer tokens issued via an App Integration are then used to authenticate requests to SpeakUp’s Public APIs.
2. Security Model and Access Control
App Integrations follow the principle of least privilege.
During creation, you must explicitly choose what the integration can access.
2.1 Issue Access
|
Access Level |
Description |
|---|---|
|
Read only |
Allows read-only access to issues and related data. |
|
Full access |
Allows viewing and updating issues and related data. |
2.2 User Access
|
Access Level |
Description |
|---|---|
|
Read only |
Allows viewing users and related data. |
Important: Permissions are enforced at the API level. If an App Integration does not have the required access, API requests will fail with an authorization error.
3. Creating an App Integration
This section describes how to create an App Integration and retrieve the credentials required to obtain a bearer token for accessing SpeakUp’s Public APIs.
3.1 Prerequisites
-
You must be logged in with an Administrator role
3.2 Navigate to App Integrations
-
Log in to SpeakUp
-
Go to Configuration → API
-
Click Create app integration
3.3 Configure the App Integration
Provide the following details:
Name
-
Must be unique
-
Only letters, numbers and spaces are allowed
Issues Access
Select the appropriate access level based on your use case.
Users Access
Select the appropriate access level (read-only).
💡 Choose the minimum access required for the integration’s purpose.
Click Add to confirm creation.
4. Viewing Credentials
After successful creation:
-
You will be redirected to the App Integration detail page
-
The following credentials will be displayed:
-
Client ID
-
Client Secret
-
Additionally, a ready-to-use cURL command is provided to help you quickly obtain an access token.
In the cURL command, replace <client_secret> with the client secret provided.
Security note: Store the Client Secret securely. Anyone with these credentials can access the APIs within the assigned permissions.
5. Authentication Flow
App Integrations use the OAuth 2.0 Client Credentials grant type to obtain access tokens.
5.1 High-Level Flow
-
Your application sends a token request to the authorization server using:
-
Client ID
-
Client Secret
-
-
The authorization server validates the credentials.
-
An access token is issued and is valid for 1 hour (3600 seconds).
-
The access token is included in API requests using the HTTP header:
Authorization: Bearer <access_token> -
SpeakUp Public APIs validate the token and authorize the request based on the App Integration’s assigned permissions.
5.2 Token Retrieval
You can obtain an access token by:
-
Using the cURL command displayed on the App Integration detail page, or
-
Performing the same request from your own application code or tooling
6. Managing Existing App Integrations
6.1 Viewing App Integrations
All created App Integrations are listed under Configuration → API, showing:
-
Integration name
Click an integration name to view its details and credentials.
6.2 Deleting an App Integration
Deleting an App Integration permanently revokes API access.
Step 1: Select the App Integration
-
Navigate to Configuration → API
-
Click the name of the App Integration to open its details page
Step 2: Delete the App Integration
-
Click Delete App Integration
-
Confirm deletion in the prompt
Step 3: Completion
-
Credentials are permanently removed
-
Any tokens issued using this integration will no longer be valid
-
You will be redirected to the App Integrations list