Account Integration API Documentation
This document is for partner developers who connect their athletes' accounts to FlexPro Grip. It covers linking an existing FlexPro Grip account, creating a new one, and signing a linked athlete into FlexPro Grip without a second password.
Table of Contents
- Overview
- What You Receive
- Environments
- How It Works
- Step 1: Send the Athlete to FlexPro Grip
- Step 2: Handle the Redirect Back
- Step 3: Exchange the Code for a Link
- Federated Sign-In
- Unlinking an Athlete
- Rules and Limits
- Error Handling
- Security Requirements
- Examples
Overview
FlexPro Grip acts as the identity provider for your app:
- Athletes only ever type their FlexPro Grip password on pages hosted by FlexPro Grip.
- Your app never receives a FlexPro Grip password, session token, or any long-lived per-athlete credential.
- After linking, you hold the pair FlexPro Grip
user_idโ yourexternal_subject. Athlete data stays available through the existing organisation APIs (/api/histories,/api/weekly_protocol_schedules). - Each integration belongs to exactly one organisation. It can never see or link athletes of another organisation.
The integration supports three things:
| Capability | What the athlete experiences |
|---|---|
| Account linking | Clicks "Connect FlexPro Grip" in your app, logs in on FlexPro Grip, clicks Allow |
| One-click onboarding | Same as above, but chooses Create account โ the new account joins the organisation |
| Federated sign-in | Clicks "Open FlexPro Grip" in your app and lands in FlexPro Grip already signed in |
What You Receive
FlexPro Grip gives you these once per organisation, through an encrypted channel (never plain email or chat):
| Item | Example | Secret? | Where it is used |
|---|---|---|---|
client_id |
fpg_Jx3k9... |
No | In the browser URL of Step 1 |
| API key | kq7N... |
Yes | In the api-key header of every server-to-server call |
| Redirect URIs | https://partner.example.com/flexprogrip/callback |
No | Registered once for your app; must match exactly |
Your redirect URIs are registered once for your whole app, not per organisation. Send FlexPro Grip your test and production callback URLs before you start.
Environments
| Environment | Base URL |
|---|---|
| Production | https://app.flexprogrip.com |
| Testing | Provided by FlexPro Grip together with your credentials |
The examples below use https://app.flexprogrip.com.
How It Works
Athlete's browser FlexPro Grip Your server
| | |
| 1. GET /oauth/authorize?client_id&redirect_uri&state&code_challenge
|--------------------------->| |
| log in or create account, then Allow |
|<---------------------------| |
| 2. 302 redirect_uri?code=...&state=... |
|---------------------------------------------------------------->|
| | 3. POST /api/oauth/links |
| |<-----------------------------------|
| | 201 { user_id, ... } |
| |----------------------------------->|
Later, federated sign-in:
| | 4. POST /api/oauth/login_tickets |
| |<-----------------------------------|
| | 201 { url, expires_in: 60 } |
| |----------------------------------->|
| 5. redirect the browser to url, athlete clicks "Continue as ..."|
|--------------------------->| signed in to FlexPro Grip |
Step 1: Send the Athlete to FlexPro Grip
Redirect the athlete's browser to:
GET /oauth/authorize
Authorize Query Parameters
| Parameter | Required | Rule |
|---|---|---|
response_type |
Yes | Must be code. |
client_id |
Yes | The client_id for this organisation. |
redirect_uri |
Yes | Must be byte-for-byte identical to one of your registered redirect URIs. |
state |
Yes | 1โ512 characters. Random, unguessable, tied to the athlete's session in your app. Returned unchanged. |
code_challenge |
Yes | PKCE challenge, 43โ128 characters (see below). |
code_challenge_method |
Yes | Must be S256. plain is rejected. |
Do not send your own athlete ID in this URL. You send it later, server-to-server, in Step 3.
Generating PKCE Values
Create a fresh code_verifier for every attempt and keep it server-side (or in the athlete's session in your app). Send only the code_challenge in the URL.
Node.js:
import crypto from "node:crypto";
const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
Python:
import base64, hashlib, secrets
code_verifier = secrets.token_urlsafe(32)
code_challenge = (
base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest())
.rstrip(b"=")
.decode()
)
Ruby:
require "securerandom"
require "digest"
require "base64"
code_verifier = SecureRandom.urlsafe_base64(32)
code_challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)
Step 2: Handle the Redirect Back
When the athlete finishes, FlexPro Grip redirects the browser to your redirect_uri.
| Outcome | Redirect |
|---|---|
| Athlete clicked Allow | redirect_uri?code=<code>&state=<state> |
| Athlete clicked Deny, or isn't eligible | redirect_uri?error=access_denied&state=<state> |
A parameter other than client_id/redirect_uri was invalid |
redirect_uri?error=invalid_request&state=<state> |
Always check that state equals the value you sent. If it doesn't, discard the response.
If client_id or redirect_uri is invalid, FlexPro Grip does not redirect. The athlete sees an error page on FlexPro Grip instead, so a mistyped or unregistered redirect URI shows up immediately during testing.
An athlete is eligible only if their account is an athlete account and a member of the integration's organisation. Athletes who aren't members see a page asking them to contact their organisation's staff, with a button back to your app (error=access_denied).
Step 3: Exchange the Code for a Link
From your server, exchange the code within 60 seconds:
POST /api/oauth/links
api-key: <your_api_key>
Content-Type: application/json
Link Request Body
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | Yes | The code from Step 2. |
code_verifier |
string | Yes | The PKCE verifier you generated in Step 1. |
redirect_uri |
string | Yes | The same redirect_uri you used in Step 1. |
external_subject |
string | Yes | Your own ID for this athlete, 1โ255 characters. Used in later calls. Numbers are accepted and stored as strings. |
{
"code": "Qm9r...",
"code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
"redirect_uri": "https://partner.example.com/flexprogrip/callback",
"external_subject": "athlete-123"
}
Link Response
201 Created for a new link, 200 OK if this athlete was already linked to the same external_subject:
{
"user_id": 4821,
"external_subject": "athlete-123",
"email": "jane@example.com",
"email_verified": false,
"first_name": "Jane",
"last_name": "Doe",
"linked_at": "2026-10-14T18:22:05Z"
}
Store user_id against your athlete. It is the same id used by /api/histories.
email_verified is true only once the athlete has confirmed their email address with FlexPro Grip. Accounts created through the connect flow start unconfirmed, so don't treat email as proof of identity while email_verified is false.
| Status | error |
Meaning |
|---|---|---|
| 400 | invalid_request |
A field is missing or malformed. |
| 400 | invalid_grant |
Code unknown, expired, already used, or redirect_uri / code_verifier doesn't match, or the athlete is no longer eligible. Start again from Step 1. |
| 401 | โ | Missing or invalid api-key, or the integration is disabled. |
| 409 | already_linked |
This athlete is linked to a different external_subject, or this external_subject is linked to a different athlete. Unlink first. |
A code is burned by the first exchange attempt, even a failed one.
Federated Sign-In
To send a linked athlete into FlexPro Grip already signed in, request a sign-in ticket from your server at the moment they click:
POST /api/oauth/login_tickets
api-key: <your_api_key>
Content-Type: application/json
{ "external_subject": "athlete-123" }
Login Ticket Response
201 Created:
{
"url": "https://app.flexprogrip.com/oauth/sign_in/9vGq...",
"expires_in": 60
}
Redirect the athlete's browser to url immediately. They see "Continue as Jane" and are signed in with one click. The URL works once and expires after 60 seconds. Don't email it, store it, or pre-generate it.
| Status | error |
Meaning |
|---|---|---|
| 400 | invalid_request |
external_subject is missing, blank, or longer than 255 characters. |
| 404 | link_not_found |
No active link for this external_subject, or the athlete is no longer eligible (for example, removed from the organisation). |
Unlinking an Athlete
DELETE /api/oauth/links/:external_subject
api-key: <your_api_key>
Percent-encode external_subject in the path (for example, org/athlete 7 becomes org%2Fathlete%207).
| Status | Meaning |
|---|---|
| 204 | Unlinked. Any outstanding sign-in URLs stop working. |
| 404 | link_not_found: no active link for this external_subject. |
Rules and Limits
- Authorization codes and sign-in tickets are single-use and valid for 60 seconds.
- Only athlete accounts that are members of the integration's organisation can be linked or signed in. Other account types can never be reached through an integration.
- Eligibility is checked on every request. Removing an athlete from the organisation, or disabling the integration, takes effect immediately.
- Links survive API key rotation. When FlexPro Grip replaces your API key, existing links keep working with the new key; athletes don't need to reconnect. Requests with the old key are rejected with
401. - One athlete โ one
external_subjectper integration. Existing links are never overwritten. - Rate limit: 60 requests per minute per API key. Exceeding it returns
429with aRetry-Afterheader (seconds).
Error Handling
HTTP Status Codes
- 200 OK: Existing link returned
- 201 Created: Link or sign-in ticket created
- 204 No Content: Link removed
- 400 Bad Request: Invalid request or code
- 401 Unauthorized: Missing/invalid API key or integration disabled
- 404 Not Found: No active link
- 409 Conflict: Already linked
- 429 Too Many Requests: Rate limited
Error Response Format
{
"error": "invalid_grant",
"error_description": "The authorization code is invalid, expired or already used, or the redirect_uri or code_verifier does not match."
}
error |
Status |
|---|---|
invalid_request |
400 |
invalid_grant |
400 |
link_not_found |
404 |
already_linked |
409 |
rate_limited |
429 |
401 responses have an empty body.
Security Requirements
- Keep the API key on your server. Never put it in a browser, mobile app, or source repository.
- Always send a random
stateand verify it on the way back. - Generate a new PKCE
code_verifierfor every attempt. - Use HTTPS redirect URIs.
- Request sign-in tickets only when the athlete clicks, and redirect straight away.
- Never log authorization codes, PKCE verifiers or sign-in URLs.
- Tell FlexPro Grip immediately if you think the API key has leaked. It will be replaced, and the old key stops working.
Examples
Exchange a Code
curl -X POST "https://app.flexprogrip.com/api/oauth/links" \
-H "api-key: $FPG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "Qm9r...",
"code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
"redirect_uri": "https://partner.example.com/flexprogrip/callback",
"external_subject": "athlete-123"
}'
Request a Sign-In URL
curl -X POST "https://app.flexprogrip.com/api/oauth/login_tickets" \
-H "api-key: $FPG_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "external_subject": "athlete-123" }'
Unlink
curl -X DELETE "https://app.flexprogrip.com/api/oauth/links/athlete-123" \
-H "api-key: $FPG_API_KEY"