OAuth Integration Guide

This guide explains how to connect your application to TeamUp using OAuth 2.0.

Whether you're a gym owner setting up an integration or a developer implementing it, this document walks you each step of prompting a user to authorize your Application and obtaining an access token that can make API requests on their behalf.

---

1. Authorization

To begin the OAuth flow, make a GET request to:

https://goteamup.com/api/v2/auth/oauth/authorize

Query Parameters

Parameter	Description
client_id	The unique ID of your application.
redirect_uri	The URL users should be redirected to after they complete authorization. Must match one of the redirect URIs configured for your app.
scope	Always include read_write. If your Application can access multiple businesses, specify a provider:<ID> scope. Scopes are space-delimited, e.g.:read_write provider:6
response_type	Set to code.
state (optional)	A value you can pass to maintain state between the request and callback (e.g., for CSRF protection or to persist app data).
code_challenge	The PKCE code challenge derived from your code_verifier. Required for mobile or public clients that can’t securely store a client secret.
login_hint (optional)	Prefills the user’s email in the login form.

Notes

• If your app is a first-party application, users won’t be asked to confirm access permissions.
• Users who aren’t logged in will be prompted to do so before being redirected to your redirect_uri.

---

2. Token Exchange

After the user grants permission, they’ll be redirected to your redirect_uri with two query parameters:
code and optionally state.

Exchange this authorization code for tokens by sending a POST request to:

https://goteamup.com/api/v2/auth/oauth/token

Request Details

• Content Type: application/x-www-form-urlencoded

Parameter	Description
client_id	Your application’s client ID.
code	The authorization code returned in the redirect.
redirect_uri	Must match the one used in the original request.
grant_type	Set to authorization_code.
code_verifier	The PKCE code verifier used to create the code_challenge.
client_secret	Optional — include this only if your app can securely store secrets (e.g., a backend service).

Successful Response

You’ll receive a JSON payload containing access and refresh tokens:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "asdfasdfasdfas32423423424jadsfkjadfs"
}

Example JWT Payload

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "johndoe@hotmail.com",
  "app_id": 123,
  "scope": "read_write provider:6",
  "iat": 1516239022,
  "exp": 1516249022,
  "auth_time": 1516239022
}

• iat: Token issue time
• exp: Expiration time (2 hours after issue)
• auth_time: When the user originally authenticated

---

3. Refreshing Tokens

Access tokens expire after 2 hours.
To obtain a new one without re-authenticating the user, make a POST request to:

https://goteamup.com/api/v2/auth/refresh_access_token

Request Details

• Content Type: application/json

Parameter	Description
refresh_token	The refresh token obtained from the token exchange step.
scope (optional)	Accepts a provider scope (e.g. provider:<ID>) if you'd like to access a different provider. Omit to continue accessing the original provider.

Response Schema

A successful refresh request returns a new set of tokens in JSON format:

{
  "access_token": "string",
  "expires_in": 7200,
  "refresh_token": "string"
}

Field	Type	Description
access_token	string	The new access token used for API requests.
expires_in	integer	Time (in seconds) until the new access token expires.
refresh_token	string	The new refresh token to use for future refresh requests.

Important Notes

• Once a refresh request succeeds, the refresh token that made the request is immediately invalidated.
  To keep your integration working, always store the new refresh token returned in the response.
• Access tokens typically expire after 2 hours, so plan to use the refresh token regularly to maintain a seamless connection without requiring the user to reauthorize.

---

4. PKCE (Proof Key for Code Exchange)

What is PKCE?

PKCE (Proof Key for Code Exchange) is an extension to OAuth 2.0 designed to make authorization more secure for mobile and single-page applications (SPAs) that cannot safely store a client secret.

In a traditional OAuth flow, an attacker who intercepts the authorization code could exchange it for tokens if they know the client’s credentials. PKCE prevents this by introducing a proof key mechanism that ties the authorization request and token exchange together.

How It Works

1. Client generates a code verifier — a random string that acts like a secret known only to the client.
2. Client creates a code challenge — a hashed and Base64 URL–encoded version of the verifier.
3. The authorization request includes the code_challenge and specifies the S256 hashing method.
4. When the authorization server returns the authorization code, it remembers the challenge.
5. The token request must include the original code_verifier.
6. The server hashes the verifier again and compares it to the stored challenge. If they match, the token exchange succeeds.

This means that even if a malicious actor intercepts the authorization code, they can’t complete the flow without the original verifier.

Why PKCE is Important

• Security for public clients: Mobile and web apps can’t keep a client_secret hidden. PKCE ensures they remain secure without one.
• Mitigates interception attacks: Prevents attackers from using stolen authorization codes to obtain tokens.
• Now standard best practice: PKCE is recommended for all OAuth clients, including those that do have client secrets, because it adds an extra layer of protection.

Example Implementation in Python

import base64
import hashlib
import secrets

def generate_pkce_code_challenge(verifier: str) -> str:
    challenge = hashlib.sha256(verifier.encode("utf-8")).digest()
    challenge = base64.urlsafe_b64encode(challenge).decode("utf-8")
    return challenge.replace("=", "")

def generate_pkce_code_verifier() -> str:
    return secrets.token_urlsafe(96)[:70]

Equivalent functionality exists in JavaScript and other languages — many OAuth libraries support PKCE natively.

---

Summary

1. Authorize: Direct users to the /authorize URL.
2. Exchange: Swap the returned code for tokens.
3. Refresh: Use the refresh token to keep access active.
4. PKCE: Required security for public or mobile clients.