Partner API · Integration guide

Build Sporty's courses into your flight-school platform

The Partner API connects your flight-school software to Sporty's online ground school. Use it to give your students access to Sporty's courses, keep your flight schools in sync, follow each student's progress, and get notified when they reach a milestone.

How it fits together

Your server talks to Sporty's in two ways. For anything about your account (your courses, your schools, the licenses you sell) it uses a partner token. To read one student's data it uses a student token, which you get after that student signs in with Sporty's and approves your app. Sporty's calls you back with webhooks.

Before you start

Get your credentials

Sporty's sets up your partner account, chooses the courses you can offer, and sends you a client ID and client secret. Your client ID identifies you on every call: you only ever see your own schools, courses, licenses and webhooks.

If you plan to connect student accounts, also send us the redirect URL(s) where students land after they approve your app, for example https://app.example.com/sportys/callback. Sporty's matches them exactly, so include the scheme, host and path you'll really use. Students see your company name and logo when they approve your app.

Base URL

Every path in this guide goes after the base URL. For example, the token endpoint is https://courses.sportys.com/altitude/oauth2/token.

Conventions

• HTTPS and JSON. Send request bodies as JSON with Content-Type: application/json. The token endpoint is the one exception: it takes a form-encoded body.
• Times are UTC in ISO 8601, for example 2026-08-03T15:57:02.668Z.
• Courses are identified by a course ID called webAppId, such as PRIVATE or INSTRUMENT. It's case-sensitive.
• Your own IDs are strings you choose: purchaseId for each sale and partnerFlightSchoolId for each school. Keep them unique and stable.
• Treat Sporty's IDs as opaque strings. Some look like UUIDs, but not all of them are.
• No pagination or rate limits today. Lists return every item. Be gentle anyway: cache the course catalog and reuse access tokens.

Quickstart

These four calls take you from credentials to a student with a course.

1. Get a partner access token

   Exchange your client ID and secret for an access token.

   Request

   curl -X POST "https://courses.sportys.com/altitude/oauth2/token" \
     -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
     -d "grant_type=client_credentials"

   Response 200

   {
     "access_token": "eyJraWQiOiJ...",
     "token_type": "Bearer",
     "expires_in": 3599
   }

   Send the token on every other call as Authorization: Bearer <access_token>.

2. List the courses you can offer

   Request

   curl "https://courses.sportys.com/altitude/oauth2/api/partner/courses" \
     -H "Authorization: Bearer $TOKEN"

   Each item's webAppId is the course ID you'll use in the next steps.

3. Register a flight school

   Request

   curl -X POST "https://courses.sportys.com/altitude/oauth2/api/partner/school" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "partnerFlightSchoolId": "fs-10482",
       "companyName": "Blue Sky Aviation",
       "isTestAccount": false,
       "enabledByUserEmail": "ops@blueskyaviation.example",
       "event": "STATUS_ENABLED"
     }'

4. Give a student a course

   Request

   curl -X POST "https://courses.sportys.com/altitude/oauth2/api/partner/purchase" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "sportysId": 1234567,
       "purchases": [
         {
           "webAppId": "PRIVATE",
           "purchaseId": "order-58213-1",
           "partnerFlightSchoolId": "fs-10482"
         }
       ]
     }'

   A 201 Created with an empty body means it worked: the student has the course. Next, read Give a student access for the details, or set up webhooks.

Key concepts

Authentication

The API uses OAuth 2.0. Every call needs an access token in the Authorization header. Which token you need depends on whose data you're touching:

Both flows use the same token endpoint, https://courses.sportys.com/altitude/oauth2/token. OpenID Connect discovery is at https://courses.sportys.com/altitude/.well-known/openid-configuration if your OAuth library can use it.

Get a partner token

Authenticate with HTTP Basic auth (client ID as the username, client secret as the password) and send grant_type=client_credentials as a form field, as in the quickstart. If Sporty's set your account up for client_secret_post, send client_id and client_secret as form fields instead.

• Reuse the token until it expires. expires_in is the lifetime in seconds, which Sporty's sets for your account. Cache the token and get a new one shortly before it runs out.
• On a 401, get a new token and retry once. A token can stop working before expires_in is up, for example while Sporty's deploys an update.
• Partner tokens don't come with a refresh token. Just request a new one.

Connect a student

To read a student's profile or progress, or to get webhooks about them, the student has to approve your app. This is the standard OAuth 2.0 authorization code flow, so most OAuth client libraries handle it for you.

1. Send the student to Sporty's

   Create a random state and a PKCE code_verifier, then redirect the student's browser to:

   Authorization URL

   https://courses.sportys.com/altitude/oauth2/authorize
     ?response_type=code
     &client_id=YOUR_CLIENT_ID
     &redirect_uri=https%3A%2F%2Fapp.example.com%2Fsportys%2Fcallback
     &scope=openid%20profile
     &state=9f2c4e81a07b4d3c8e5f6a1b2c3d4e5f
     &code_challenge=BASE64URL_SHA256_OF_VERIFIER
     &code_challenge_method=S256

   Ask for openid profile. profile lets you read /oauth2/api/me, and the approval itself is what turns on webhooks for this student.

   Use letters and digits in state

   Use a value like 32 random hex characters. Values that contain - or _, such as UUIDs or base64url strings, make the sign-in fail before the student is sent back to you.

2. The student signs in and approves

   The student logs in with their Sporty's account and approves your app; they only see this screen the first time. Sporty's then redirects to your redirect_uri with ?code=…&state=…. Check that state matches what you sent.

   If the student cancels, Sporty's doesn't redirect back to you at all, so don't wait on a callback forever.

3. Exchange the code for tokens

   Do this right away: codes expire after a few minutes.

   Request

   curl -X POST "https://courses.sportys.com/altitude/oauth2/token" \
     -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
     -d "grant_type=authorization_code" \
     -d "code=CODE_FROM_CALLBACK" \
     -d "redirect_uri=https://app.example.com/sportys/callback" \
     -d "code_verifier=YOUR_CODE_VERIFIER"

   The response has an access_token, a refresh_token and an id_token. Store the refresh token securely against the student's record in your system.

4. Call the student endpoints, and refresh when needed

   Use the access token on /oauth2/api/me and /oauth2/api/courses/{webAppId}/progress. When it expires, get a new one without involving the student:

   Request

   curl -X POST "https://courses.sportys.com/altitude/oauth2/token" \
     -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=STORED_REFRESH_TOKEN"

   The refresh token stays the same each time you use it, until it expires. If a refresh fails with invalid_grant, the refresh token expired or the student disconnected your app: ask them to connect again.

Optional: add the student to one of your schools

Instead of a random state, you can send a JSON object encoded in standard Base64 (not base64url) with your partnerFlightSchoolId as schoolId. Put a random value in it too, so state still protects the sign-in. When the student approves, Sporty's adds them to that school, as long as you've registered the school and Sporty's has linked it to a school on Sporty's.

{ "schoolId": "fs-10482", "nonce": "9f2c4e81a07b4d3c8e5f6a1b2c3d4e5f" }

URL-encode the Base64 string when you put it in the authorization URL, because it can contain +, / and =.

Show your course catalog

Use these two calls to list the courses you can offer and to show what's inside each one, for example to build a course picker or to link a student straight to a lesson.

List your courses

[
  {
    "webAppId": "PRIVATE",
    "shortName": "Private Pilot",
    "totalElements": 170,
    "totalRequiredElements": 133,
    "courseLastUpdateDateTime": "2026-07-16T19:30:10.959Z",
    "elementsLastUpdateDateTime": "2026-06-16T17:46:05.123Z",
    "metadata": {
      "url": "https://courses.sportys.com/training/portal/course/PRIVATE"
    }
  },
  {
    "webAppId": "INSTRUMENT",
    "shortName": "Instrument Rating",
    "totalElements": 105,
    "totalRequiredElements": 87,
    "courseLastUpdateDateTime": "2026-07-16T19:30:10.888Z",
    "elementsLastUpdateDateTime": "2026-04-22T01:46:08.649Z",
    "metadata": {
      "url": "https://courses.sportys.com/training/portal/course/INSTRUMENT"
    }
  }
]

The list isn't in any particular order. Sort it however suits your UI.

Get one course with its lessons

Returns the same summary plus volumes, each with its elements. It covers the course's video training volumes.

{
  "webAppId": "PRIVATE",
  "shortName": "Private Pilot",
  "totalElements": 170,
  "totalRequiredElements": 133,
  "courseLastUpdateDateTime": "2026-07-16T19:30:10.959Z",
  "elementsLastUpdateDateTime": "2026-06-16T17:46:05.123Z",
  "metadata": { "url": "https://courses.sportys.com/training/portal/course/PRIVATE" },
  "volumes": [
    {
      "uuid": "1a3ff1fa-1d1f-4528-9a71-5e1ebee8d88f",
      "description": "Your First Few Hours",
      "sectionId": "1",
      "order": 3,
      "totalElements": 26,
      "totalRequiredElements": 26,
      "elements": [
        {
          "uuid": "8af588a3-6bd4-4525-9fb9-ddb248d6eed8",
          "type": "Video",
          "name": "Getting Started with Sporty's Learn to Fly Course",
          "required": true,
          "order": 0,
          "metadata": {
            "runtime": "00:05:27",
            "runtimeSeconds": 327,
            "url": "https://courses.sportys.com/training/portal/course/PRIVATE/volumes/VIDEO_TRAINING/1a3ff1fa-1d1f-4528-9a71-5e1ebee8d88f/8af588a3-6bd4-4525-9fb9-ddb248d6eed8"
          }
        }
      ]
    }
  ]
}

• Volumes are in course order (by sectionId). Don't use the volume's order field; it doesn't reflect the course.
• Elements are in order within their volume, and their order field matches.
• type is Video, InteractiveLesson, Quiz or Document.
• metadata.url opens the lesson on Sporty's. runtime and runtimeSeconds are only set for videos; they're null for other types.
• uuid is the element's ID. It's a UUID for videos and interactive lessons, but not for quizzes and documents, so store it as a plain string.

If the course doesn't exist you get 404. If it exists but isn't in your catalog you get 401 with a message; see Errors.

Keep schools in sync

Register each flight school on your platform with Sporty's, using your own ID for it. You'll use that ID when you give its students a course.

Create or update a school

Posting a partnerFlightSchoolId you've already used updates that school, so use this call for both creating and updating. It returns 200 with an empty body.

Disabling a school marks it inactive. It doesn't change any student's access.

List your schools

[
  {
    "id": 42974776,
    "partnerFlightSchoolId": "fs-10482",
    "schoolId": 42908793,
    "companyName": "Blue Sky Aviation",
    "isTestAccount": false,
    "enabledByUserEmail": "ops@blueskyaviation.example",
    "createDate": "2026-01-21T18:54:24.058Z",
    "schoolCode": "BLUE_SKY",
    "partnerSchoolStatus": "ENABLED"
  },
  {
    "id": 43857884,
    "partnerFlightSchoolId": "fs-20931",
    "schoolId": null,
    "companyName": "UNKNOWN",
    "isTestAccount": false,
    "enabledByUserEmail": "UNKNOWN",
    "createDate": "2026-08-03T15:53:13.019Z",
    "schoolCode": null,
    "partnerSchoolStatus": "ENABLED"
  }
]

• schoolId and schoolCode are filled in once Sporty's links your school to a school on Sporty's. Until then they're null.
• Schools named UNKNOWN are placeholders. Sporty's creates one when you give a student a course with a partnerFlightSchoolId you haven't registered. Post the school to fill in its details, and register schools before you sell through them.

Give a student access to a course

When a student buys a Sporty's course through you, call this to give them a license. One call can grant several courses.

Identify the student

The student needs a Sporty's account. Identify them in one of two ways:

Request

{
  "sportysId": 1234567,
  "purchases": [
    {
      "webAppId": "PRIVATE",
      "purchaseId": "order-58213-1",
      "partnerFlightSchoolId": "fs-10482"
    },
    {
      "webAppId": "INSTRUMENT",
      "purchaseId": "order-58213-2",
      "partnerFlightSchoolId": "fs-10482"
    }
  ]
}

{
  "email": "jordan.rivera@example.com",
  "firstName": "Jordan",
  "lastName": "Rivera",
  "purchases": [
    {
      "webAppId": "PRIVATE",
      "purchaseId": "order-58213-1",
      "partnerFlightSchoolId": "fs-10482",
      "date": "2026-11-12T15:00:00Z"
    }
  ]
}

What happens

• 201 Created, empty body: the student has every course in the request. Each license runs for the course's standard term from its start date.
• All or nothing. If any course in the request fails, none are granted. Fix the problem and send the whole request again.
• Already licensed: if the student already has, or had, a license for a course, that course is skipped and the call still succeeds. Renewing an expired license through the API isn't supported yet; contact Sporty's.
• Connected students also trigger a COURSE_PURCHASED webhook.

Retries and duplicates

• Retrying is safe if you reuse the same purchaseIds: the student keeps the license they already have.
• Never reuse a purchaseId for a different student. Sporty's rejects it with 409 Conflict.
• Send one school per request. If a student buys courses through two schools, make two calls.

Report a purchase for a student who isn't connected

Use this when a student buys a Sporty's course through you but hasn't connected a Sporty's account. It records the sale with Sporty's. It doesn't create an account or give the student access; to do that, use /partner/purchase.

{
  "courseId": "PRIVATE",
  "purchaseId": "order-58214-1",
  "companyId": "fs-10482",
  "user": {
    "id": "u-88412",
    "studentId": "S-2026-0193",
    "email": "sam.patel@example.com",
    "firstName": "Sam",
    "lastName": "Patel"
  }
}

It returns 200 with an empty body. Send each sale once: Sporty's doesn't combine repeated reports. Errors are the same as for purchases: 404 for an unknown course, 401 for a course outside your catalog.

Show a student's progress

Once a student has connected their account, use their student token to read who they are and how far along they are. Neither call accepts a partner token.

Get the student's profile

{
  "id": 50211873,
  "sportysId": 1234567,
  "email": "jordan.rivera@example.com",
  "firstName": "Jordan",
  "lastName": "Rivera",
  "createdDate": "2026-03-02T14:11:09Z",
  "address": {
    "address": null,
    "city": null,
    "state": null,
    "zip": null
  },
  "activeLicenses": ["PRIVATE", "SPORT"],
  "inactiveLicenses": []
}

Get progress in one course

{
  "completedElements": [
    "8af588a3-6bd4-4525-9fb9-ddb248d6eed8",
    "9b31980f-e74c-42e4-b47c-590b95d458a3"
  ],
  "tests": [
    {
      "id": 61540032,
      "uuid": "5b0e7d0c-2c1f-4a51-9d0e-3f1c2b7a9e41",
      "completedDate": "2026-08-03T15:57:02.668Z",
      "questions": 60,
      "correct": 55,
      "grade": 92,
      "pass": true
    }
  ],
  "milestones": [],
  "courseRequirement": {
    "passingGrade": 80,
    "passingTests": 2
  },
  "certificates": [],
  "completion": {
    "percentComplete": 24,
    "requiredPercentComplete": 31,
    "videoPercentComplete": 24,
    "requiredVideoPercentComplete": 31,
    "displayedPercentComplete": 31,
    "videoWatchedLength": { "hours": 4, "minutes": 12, "seconds": 37 },
    "elements": {
      "elements": 170,
      "requiredElements": 133,
      "completedElements": 41,
      "completedRequiredElements": 41
    }
  }
}

How to use it:

• Progress bar: show completion.displayedPercentComplete. It's the figure Sporty's shows the student, so the two stay consistent. Clamp it to 0–100 in your UI.
• Video checklist: completedElements lists the uuid of every video the student has finished. Match them against the course details to tick videos off.
• Practice tests: each entry in tests is one attempt. courseRequirement says what the course asks for, for example two passed tests at 80% or better.
• Milestones: milestones lists COURSE_COMPLETED, WRITTEN_EXAM_ELIGIBLE and WRITTEN_EXAM_REQUESTED with the date the student first reached each one.
• Certificates: earned certificates (such as an exam endorsement or a course completion certificate) have pdfUrl and jpgUrl links. The links expire after 24 hours, so fetch progress again when the student wants one; don't store them.
• Watch time: videoWatchedLength counts each video once; totalVideoWatchedLength includes re-watches.

A student without a license for the course still gets 200, with the license-based figures at zero. An unknown webAppId returns 404.

Webhooks

Webhooks tell your server when something happens to a student: a course was bought, a lesson or course was finished, or the student became ready for the FAA written exam. Sporty's sends an HTTPS POST with a small JSON body to the URL you register.

Set up

1. Choose how Sporty's proves it's Sporty's

   Pick a long random secret and tell Sporty's how to send it. One setting covers all your webhooks. Sporty's doesn't send any events until it's set.

   PUT/oauth2/api/partner/webhook-configPartner token
   Request body

   {
     "authenticationType": "BEARER_TOKEN",
     "tokenValue": "whsec_4f9a1c7e2b8d6a3f5e0c9b7d1a2e4f6c"
   }

   authenticationType	Header on each webhook
   BEARER_TOKEN	Authorization: Bearer <tokenValue>
   API_KEY	x-api-key: <tokenValue>
   CUSTOM_HEADER	<customHeaderName>: <tokenValue>. Also send customHeaderName.

   Check that header on every request and reject anything that doesn't match. GET /oauth2/api/partner/webhook-config shows the current setting.

2. Register a URL for each event you want

   POST/oauth2/api/partner/webhooksPartner token
   Request body

   {
     "eventType": "COURSE_COMPLETED",
     "url": "https://app.example.com/sportys/webhooks",
     "enabled": true
   }

   Response 200

   {
     "id": 812,
     "eventType": "COURSE_COMPLETED",
     "url": "https://app.example.com/sportys/webhooks",
     "enabled": true
   }

   • Set enabled to true. If you leave it out, the webhook is created switched off.
   • One webhook per event type. The same URL can take every event; use the event field to tell them apart. If you register the same event twice, you get every event twice.
   • Use an HTTPS URL.

Change or remove a webhook

Events

COURSE_PURCHASED, COURSE_COMPLETED, WRITTEN_EXAM_ELIGIBLE and WRITTEN_EXAM_REQUESTED each happen once per student and course.

Payload

POST /sportys/webhooks HTTP/1.1
Host: app.example.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer whsec_4f9a1c7e2b8d6a3f5e0c9b7d1a2e4f6c

{
  "sportysId": "1234567",
  "userId": "1234567",
  "webAppId": "PRIVATE",
  "courseId": "PRIVATE",
  "event": "LESSON_COMPLETED",
  "timestamp": "2026-11-12T15:04:05.482Z",
  "eventDetails": {
    "elementUuid": "9b31980f-e74c-42e4-b47c-590b95d458a3",
    "elementType": "Video",
    "elementTitle": "When Should You Fly?"
  }
}

Delivery and retries

• Answer with any 2xx within 10 seconds. Anything else, including a timeout, counts as a failure. Save the event and do the work afterwards.
• Failures are retried later with the same body, to the webhook's current URL and authentication, until a delivery succeeds. Disabling a webhook pauses its retries; deleting it cancels them.
• Expect duplicates. Treat event, userId, courseId and eventDetails.elementUuid together as the event's identity and ignore repeats.
• Don't rely on order. For example, WRITTEN_EXAM_ELIGIBLE can arrive before COURSE_COMPLETED.
• An event can arrive a moment before the API shows the change. If progress looks unchanged right after an event, fetch it again a few seconds later.

Test your endpoint

Register a webhook with "eventType": "TEST" and ask your Sporty's contact to send a test event. It arrives with your authentication header and this body:

{ "event": "TEST", "timestamp": "2026-11-12T15:04:05.482Z" }

A failed test is retried like any other event, so disable or delete the TEST webhook when you're done.

Errors

Errors use standard HTTP status codes. Most come with a JSON body (application/problem+json) that has a status and a title or message. Authentication failures come with an empty body.

{
  "type": "https://www.jhipster.tech/problem/entity-not-found",
  "title": "Course not found for web app id: PRIVTE",
  "status": 404
}

{
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "status": 401,
  "path": "/altitude/oauth2/api/partner/purchase",
  "message": "Licenses cannot be submitted for the course MULTIENGINE"
}

{
  "type": "https://www.jhipster.tech/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "path": "/altitude/oauth2/api/partner/purchase",
  "message": "error.validation",
  "fieldErrors": [
    { "objectName": "partnerPurchaseRequest", "field": "purchases", "message": "must not be empty" }
  ]
}

Match on the status code, not the message text: messages can change.

All endpoints

Paths are relative to https://courses.sportys.com/altitude. The API reference has every field, and the OpenAPI file imports into Postman or Insomnia.

Go-live checklist

• The client secret lives only on your server, in a secrets store.
• Partner tokens are cached and reused. A 401 gets a new token and one retry.
• Every school is registered before you sell through it, with an enabledByUserEmail.
• Every sale has its own purchaseId, and retries reuse it.
• Each purchase request covers one school.
• You identify connected students by sportysId.
• The sign-in asks for openid profile, uses a state without - or _, and checks state on return.
• Refresh tokens are stored encrypted, and an invalid_grant asks the student to connect again.
• Webhook authentication is set, and each webhook is registered once with "enabled": true and an HTTPS URL.
• Your webhook endpoint checks the auth header, answers within 10 seconds, ignores duplicates and doesn't depend on order.
• Percentages are clamped to 0–100, and certificate links are fetched fresh, not stored.

Support

Your Sporty's partner contact can issue or replace credentials, add courses to your catalog, register redirect URLs, link your schools on Sporty's, and send test webhooks.

When you report a problem, include the time (UTC), the endpoint, the HTTP status and response body, and the purchaseId or partnerFlightSchoolId involved. Never send your client secret or a student's tokens.