Authentication and Authorization
The Firstup API authentication model is based on OAuth 2.0, ensuring secure access to API endpoints. Every request must include an access token, which identifies the authenticated user (if applicable) and the program being accessed. Requests made with an access token function similarly to actions performed in Program Studio or the Firstup mobile apps as a logged-in user.
To request access to the API, contact support.
User authentication and OAuth token requests are handled by a dedicated authentication server at:
- US1: https://auth.socialchorus.com
- US2: https://auth.us2.onfirstup.com
- EU: https://auth.onfirstup.eu
Authentication Methods
Firstup supports three authentication methods to meet different integration needs:
Choosing the Right Method
Look at our main Authentication methods article for a full breakdown.
| Use Case | Recommended Method |
|---|---|
| Mobile or browser-based app | Authorization Code Grant with PKCE |
| App that needs to act on user’s behalf | Authorization Code Grant |
| Backend system or automated process | Client Credentials Grant |
| Identity delegation or SSO integrations | JWT Bearer Token Grant |
If you're unsure which method fits your use case, please contact your Firstup representative for assistance.
Program Scoping
When registering an OAuth app, you'll need to define which program(s) it can access. The API scopes assigned to the app determine the permissions available for that program.
Scopes must match the API operations you intend to use.
Using an OAuth 2.0 Library
To simplify authentication, use an OAuth 2.0 library such as:
- Node.js: simple-oauth2
- Python: requests-oauthlib
- Java: Spring Security OAuth
Example using Python
import requests
token_url = "https://auth.socialchorus.com/oauth/token"
data = {
"grant_type": "authorization_code",
"code": "AUTH_CODE_HERE",
"redirect_uri": "YOUR_REDIRECT_URI",
"client_id": "YOUR_CLIENT_ID",
"code_verifier": "YOUR_GENERATED_VERIFIER"
}
response = requests.post(token_url, data=data)
print(response.json())Auth Scope List and Definitions
Different scopes grant different permissions for API access.
The following is a list of all possible auth scopes that can be requested for an access token. The required scopes for each endpoint are listed in the API Endpoint Reference. If scopes are not specified in the auth request, the default scopes for your OAuth application will be granted.
Click here to request API scopes.
| Scope | Description |
|---|---|
| admin_login | Login using an admin login UI. (Uncommon) |
| content.read | View and list details of content in your program. |
| content.write | Create, view, and update content in your program. |
| filter.initiative_tags.id | Leave blank to return the default of all content. Alternatively, pass an array or comma separated list of initiative tags to limit the content. An initiative is a tag used for reporting purposes to help track business objectives through topics and campaigns by reporting on performance and engagement. |
| content.videos.download | Download video content from content posts. |
| content.replication.audit | View content replication status associated with manageable content in your program. |
| feeds.read | View your feeds. |
| feeds.rendered.read | View rendered content from feed posts. |
| feeds.engage | View your feeds and engage with posts (likes, bookmarks, etc). |
| openid | View the authenticated user's OpenID profile information. |
| profile | View your basic profile information. |
| View your email addresses. | |
| address | View your physical addresses. |
| phone | View your phone numbers. |
| employment | View your employment information. |
| public | View the authenticated user's profile information. |
| users.read | View and list details of users in your program. |
| users.write | Create, view, and update users in your program. |
| groups.read | View and list details of groups in your program. |
| groups.write | Create, view, and update groups in your program. |
| webhooks.read | View and list details of webhook subscriptions in your program. |
| webhooks.write | Create, view, and update webhook subscriptions in your program. |
Security Considerations
You will be assigned a “Client ID” and a “Client Secret” by Firstup. Protect all credentials and tokens carefully and be especially careful with Client Secret. Notify Firstup immediately if you believe there is any chance these values have been compromised and we will be happy to replace them.
Access tokens expire after 2 hours. Authorization codes expire in 10 minutes. Refresh tokens are valid as long as the client app is registered with the authorization server and the user continues to give it consent.
Protecting Client Secrets
- Never expose your client secret in public repositories.
- Store credentials securely (e.g., environment variables, secret management tools).
Handling JWT Tokens Securely
- Keep your private key secure—do not expose it in your codebase.
- Set a short expiration time (exp claim) for JWT tokens.
- Use HTTPS to transmit JWT tokens securely.
Token Expiration & Refresh
- Access tokens expire after 2 hours and must be refreshed when needed.
- Authorization codes expire after 10 minutes.
- The refresh token mechanism allows apps to obtain new access tokens automatically.