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

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 โ†” your external_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_subject per integration. Existing links are never overwritten.
  • Rate limit: 60 requests per minute per API key. Exceeding it returns 429 with a Retry-After header (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 state and verify it on the way back.
  • Generate a new PKCE code_verifier for 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"