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.
Please reach out to TeamUp's customer support if you'd like a M2M token and we'll securely provision one for you. In the future, we'll allow you to manage and create them directly in your business dashboard.
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.
Bearer token example:
Authorization: Bearer <TOKEN>
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 |