Authentication
TeamUp’s API supports several authentication methods to help your Application connect securely.
The method you choose depends on whether your app acts on behalf of a user (like a trainer or customer) or on behalf of your business as a whole.
Authentication Methods
OAuth (Recommended)
OAuth allows your Application to request access to TeamUp on behalf of an end user - for example, a trainer or customer.
It uses a token called a bearer token, so your app never needs to handle the user’s TeamUp password directly.
When users connect, they’ll see TeamUp’s familiar login screen and will be prompted to authorize your Application. Once they do, your app receives a temporary access token with their permissions.
We provide step-by-step documentation to guide your team through this setup.
Common use cases:
- A mobile app for freelance trainers to manage their schedule and appointment availability
- A branded customer website showing upcoming classes and allowing users to book spots
M2M Tokens
Some integrations need to act on behalf of your business, not an individual user. In these cases, you can use a machine-to-machine (M2M) token tied to your organization as a while.
M2M tokens are ideal for server-to-server or background integrations that don't involve user logins.
TeamUp does not support the OAuth client_credentials grant or static API keys — the OAuth token endpoint only accepts grant_type=authorization_code. If you're looking for an "API key" for server-to-server access, an M2M token is the supported equivalent.
You can create and manage M2M tokens directly from your business dashboard. For a step-by-step guide, see Creating a Machine-to-Machine (M2M) Token.
Common use cases:
- A reporting system that periodically pulls business metrics from TeamUp for analysis
- A webhook processor that receives TeamUp event notifications and fetches additional data as needed
Direct Authentication
In some cases, you may want a fully branded login experience that skips the OAuth authorization screen. This is possible via Direct Authentication, but it comes with additional security risks because your application will directly handle user passwords.
Due to this, we only enable Direct Authentication after reviewing your use case. If approved, we’ll issue your developers a secondary secret for securely calling the Password Login endpoint, which returns an access token.
Making Requests
All authenticated requests must include your credential in the HTTP Authorization header.
OAuth access token example:
For an end-user access token obtained from TeamUp's OAuth flow:
Authorization: Bearer <TOKEN>
M2M token example:
For an M2M token:
Authorization: Bearer <TOKEN>
Which Credential Is Which?
Creating an API Application gives you several different strings, and TeamUp has more than one kind of token. They are not interchangeable — sending the wrong one is the most common integration mistake we see.
| Credential | Looks like | Where it comes from | How to send it |
|---|---|---|---|
| Client ID / Client Secret | Opaque strings | Shown when you create your API Application | Only as the client_id / client_secret parameters in the OAuth flow — never in the Authorization header |
| OAuth access token | A JWT — three base64 segments separated by dots (xxx.yyy.zzz) | Returned by the OAuth token endpoint after a user authorizes your app | Authorization: Bearer <ACCESS_TOKEN> |
| M2M token | Opaque key (no dots) | Created in your business dashboard | Authorization: Bearer <M2M_TOKEN> |
Troubleshooting: Wrong Token
The Authorization header must have the form Bearer <token>. If the prefix is missing or malformed, the API doesn't recognize the header at all and treats the request as unauthenticated, so the resulting error mentions authentication or permissions rather than a malformed header.
| You see | Likely cause |
|---|---|
401 with code authentication_failed ("Incorrect authentication credentials."), even though you sent a token | The Bearer prefix is missing or malformed — send the header exactly as Authorization: Bearer <token>. |
401 "The token you provided is expired or invalid" | The value isn't an active token — commonly the Client Secret pasted where a token belongs, or a revoked/expired token. |
See Errors for the general error response format.
Request Modes
When using OAuth access tokens, the level of access your integration receives depends on the authenticated user’s role and permissions in TeamUp. If using a M2M token, your integration will always make requests in Provider mode under the admin permissions.
| Mode | Who | Example Access |
|---|---|---|
| Customer | A user who has signed up at your business. | View their own Customer object |
| Provider | A staff member at your business. | View or manage all customers, if granted the customers or admin permission. |
| Unregistered Customer | A visitor who hasn’t signed up yet. | View only public content (e.g., class schedule) |
Each API endpoint lists which roles can perform which actions.
For example, the GET /customers endpoint specifies:
Providers – Any staff member can perform this action.
Customers – Customers can view their own record or a family member’s.
Unregistered Customers – No access.
Explicit Mode
Sometimes, the same person may be both a customer and a staff member. To clarify which mode your request should operate in, include the following header:
TeamUp-Request-Mode: provider
or
TeamUp-Request-Mode: customer
Explicit Provider
For franchises or multi-location businesses, your access token may be linked to multiple providers. Use this header to specify which one the request should act on:
TeamUp-Provider-ID: 123
Summary
| Method | Acts As | Use For | Security Level |
|---|---|---|---|
| OAuth | Individual user | Mobile/web apps with user login | 🔒 Highest |
| M2M Key | Your business | Server-to-server integrations | 🔐 High |
| Direct Auth | Individual user | Fully branded login experiences | ⚠️ Requires approval. Use with caution |