Equipment Vendor API (for standalone clients) (1.2.0)

At EGYM, we believe that fitness is the soul of healthy living. Work together with partners to help us bringing new ways of working out to millions of gym members, and new ways of prescribing exercises to hundred of thousands of gym trainers, all around the world.

EGYM provides a Fitness Platform for the Connected Gym so you can help us with the mission to make the gym work for everyone. EGYM provides a global account that is not scoped for a specific tenant, brand or gym. The account is called EGYM ID. The EGYM ID allows users to use different services of the gym. The EGYM ID is used for the login to EGYM hardware and software products and conneceted equipment.

EGYM works with the best of breed of the fitness industry. In this documentation, we provide tools and info needed to build a variety of workout experiences that integrate directly with the EGYM Ecosystem. We are happy to welcome you as a partner of EGYM.

📦 Changelog of Documentation

Version	Changes
1.2.0	✅ Added support for Genius Training Plans — see [`GET /api/v1/cardio/training-plans`] and [`GET /api/v1/strength/training-plans`]
1.1.0	🔐 Introduced NFC-based login via Apple/Google Wallet — see `POST /api/v1/oauth/token`

🔐 Authentication

The Equipment Vendor API authentication is based on the OAuth 2.0 as specified in the RFC6749, more concretely on the Resource Owner Password Credentials Grant due to constraint environment that can be found in our partner devices, i.e. devices with no screen or using the RFID for user identification.

Currently, different methods for obtaining the Access Token are made available:

By specifying user credentials
By specifying RFID
By specifying NFC (Wallet) credentials (since v1.1.0)

The OAuth client_id and client_secret are issued by EGYM to each partner (vendor) for each gym. These are used in a Basic authentication header as:

Authorization: Basic Base64(client_id:client_secret)

🔑 User Credentials (EGYM ID)

This is the classic Resource Owner Password Grant.

POST /api/v1/oauth/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=password&machine_type=bike&serial_number=ser123&username=johndoe&password=•••

📶 User RFID

POST /api/v1/oauth/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=rfid&machine_type=bike&serial_number=ser123&rfid=AB12CD34&rfid_format=MIFARE

Introduced in v1.1.0

This method uses NFC payloads from Apple/Google Wallet. Use grant_type=nfc and supply:

payload: the NFC data string
transponder_type: either APPLE or GOOGLE
One of:
- issuer_id: the Wallet issuer identifier (e.g., com.egym.apple)
- configuration_index: the DotOrigin VTAP slot ID

Examples:

POST /api/v1/oauth/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=nfc&machine_type=bike&serial_number=ser123&payload=abc123&transponder_type=APPLE&issuer_id=com.egym.apple

POST /api/v1/oauth/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=nfc&machine_type=bike&serial_number=ser123&payload=abc123&transponder_type=GOOGLE&issuer_id=123456789

POST /api/v1/oauth/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=nfc&machine_type=bike&serial_number=ser123&payload=abc123&configuration_index=2

📜 Terms and Conditions Handling

Some users may not have accepted the latest EGYM Terms and Conditions (T&C). In that case, the user details will indicate that the user did not accepted them yet and partners must handle T&C interaction:

1. Retrieve the T&C and privacy policy

GET /api/v1/ressources/terms-and-conditions
Content-Type: text/html

locale=en_US

GET /api/v1/ressources/privacy-policy
Content-Type: text/html

locale=en_US

Response will be terms.

2. Prompt the user to accept or decline

If accepted, proceed to step 3
If declined, exit the login flow gracefully

3. Submit confirmation of acceptance

PUT /api/v1/users/terms-and-conditions
Authorization: Bearer {access_token}
Content-Type: application/json

locale=en_US

⏱ Rate Limit

Authentication is rate-limited per client_id: 10 requests per second.

🔄 Integration Flow Overview

[Authenticate (POST /oauth/token)]
              ↓
[Get User Details (GET /users)]
              ↓
  ┌────────────────────────────┬────────────────────────────┐
  │                            │                            │
  │   Fitness Equipment        │   Measurement Devices       │
  │                            │                            │
  │ - Get Training Plan        │ - Submit Measurements       │
  │   → GET /training-plans    │   → POST /measurements/*    │
  │ - Submit Workout           │                            │
  │   → POST /workouts         │                            │
  └────────────────────────────┴────────────────────────────┘

⚠️ Error Handling

All endpoints return descriptive errors when something goes wrong.

Common HTTP Status Codes

Code	Meaning	Notes
200	OK	Success
204	No Content	Success, no response body
400	Bad Request	Validation or field error
401	Unauthorized	Missing or invalid auth - credentials are invalid
403	Forbidden	Insufficient permission - endpoint is not available for equipment type
404	Not Found	Resource doesn't exist - unknown RFID
500	Internal Error	Something unexpected

Sample Error Response

{
  "message": "Invalid input",
  "fieldErrors": [
    {
      "name": "username",
      "message": "Must not be null"
    }
  ]
}

If you have any questions or need help integrating, contact us at integrations@egym.com.

📝 Integration FAQ – Standalone Devices API

This section addresses common technical integration questions specific to the Standalone Devices model.

EGYM ID Login (grant_type=password): EGYM Username & password
RFID Login (grant_type=rfid): RFID number + format
NFC Login (grant_type=nfc): NFC payload + issuer ID or configuration index

2. Handling Terms & Conditions

If the user has not accepted the latest Terms & Conditions (T&C):

Retrieve T&C URL: GET /users/{userId}/terms
Display link to user for acceptance/rejection
If accepted: POST /users/{userId}/terms/accept
If rejected: exit the login flow gracefully

3. Key Endpoints for Standalone Integrations

Authentication: POST /oauth/token
User details: GET /users
Training plan: GET /training-plans
Workout results: POST /workouts
Measurements: POST /measurements/*

4. Error Handling Best Practices

401 Unauthorized: Invalid/missing credentials or token
403 Forbidden: Permission issue
429 Too Many Requests: Rate limit exceeded; retry after delay
Important: Provide meaningful error messages to the user (not just error codes, ideally with localized description), or silently retry when user experience requires

5. Rate Limits

Authentication: 10 requests/second per client_id
Other endpoints: See API documentation

6. Testing

Use the EGYM Sandbox with provided test credentials.
Test credentials are prodvided by EGYM
Test login flows, training plan retrieval, workout submission, and T&C handling

7. What if I send the same measurement twice?**

Use a different uniqueMeasurementId each time.

.When should I use `issuerId` vs `configurationIndex` in NFC?**

These are alternatives for identifying the wallet pass source. Provide one depending on the integration project with EGYM. Configuration Index is only supported when using the Dot Origin VTAP readers.

Download OpenAPI description

partner-api.json

partner-api.yaml

Overview

URL

https://egym.com/

EGYM GmbH

support@egym.com

License

Pending License

Languages

Servers

Mock server

https://developer.egym.com/_mock/equipment/partner-api

Test (ext-1)

https://partner-api.ext-1.test.co.egym.coffee

Production

https://partner-api.api.egym.com