Embed Tokens

Embed tokens allow you to display Rhumby widgets (standings, results, schedules, registration) on external websites. Tokens scope widget access to specific events and origins.

Token Format

All embed tokens have the prefix emb_ followed by a URL-safe random string:

emb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Unlike API keys, embed tokens are not secret. They are designed to be embedded in public JavaScript and restrict access via allowed origins and event filters.

Endpoints

GET/api/v1/embed-tokens

List organization's embed tokens

POST/api/v1/embed-tokens

Create a new embed token

DELETE/api/v1/embed-tokens?id=:id

Deactivate an embed token

List Embed Tokens

Retrieve all embed tokens for a specific organization. Requires organization membership.

GET /api/v1/embed-tokens?organizationId=:orgId

Query Parameters

Parameter	Type	Required	Description
`organizationId`	`string`	Yes	UUID of the organization

Example Request

curl "https://rhumby.com/api/v1/embed-tokens?organizationId=org_abc123" \
  -H "Cookie: session=..."

This endpoint requires session authentication (logged in via web app). You must be an active member of the organization.

Example Response

{
  "data": [
    {
      "id": "embt_123",
      "name": "Club Website - Standings Widget",
      "token": "emb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "allowedOrigins": ["https://sarasotasailing.org", "https://www.sarasotasailing.org"],
      "allowedEvents": null,
      "views": ["standings", "schedule"],
      "theme": {
        "primaryColor": "#003366",
        "font": "Inter"
      },
      "active": true,
      "createdAt": "2026-01-10T09:00:00Z"
    },
    {
      "id": "embt_456",
      "name": "Friday Night Series Widget",
      "token": "emb_x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2",
      "allowedOrigins": null,
      "allowedEvents": ["evt_fridaynight2026"],
      "views": ["results", "standings"],
      "theme": null,
      "active": true,
      "createdAt": "2026-02-15T14:30:00Z"
    }
  ]
}

Parameter	Type	Required	Description
`id`	`string`	No	Unique token identifier
`name`	`string`	No	Human-readable token name
`token`	`string`	No	The embed token (prefixed with emb_)
`allowedOrigins`	`array`	No	Array of allowed origin URLs. Null means all origins allowed (not recommended for production).
`allowedEvents`	`array`	No	Array of event UUIDs this token can access. Null means all organization events.
`views`	`array`	No	Widget types enabled: "standings", "results", "schedule", "register"
`theme`	`object`	No	Custom theme overrides (colors, fonts, etc.). Null uses default theme.
`active`	`boolean`	No	Whether the token is active
`createdAt`	`string`	No	ISO 8601 timestamp of token creation

Create Embed Token

Generate a new embed token with specific widget permissions and origin restrictions.

POST /api/v1/embed-tokens

Request Body

Parameter	Type	Required	Description
`name`	`string`	Yes	Human-readable name for the token (max 100 characters)
`organizationId`	`string`	Yes	UUID of the organization this token belongs to
`allowedOrigins`	`array`	No	Array of allowed origin URLs. Omit or set to null to allow all origins (not recommended).
`allowedEvents`	`array`	No	Array of event UUIDs. Omit or set to null to allow all organization events.
`views`	`array`	Yes	Widget types to enable: "standings", "results", "schedule", "register"
`theme`	`object`	No	Custom theme object with primaryColor, secondaryColor, font, etc.

Example Request

curl -X POST "https://rhumby.com/api/v1/embed-tokens" \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Club Website - Results Widget",
    "organizationId": "org_abc123",
    "allowedOrigins": ["https://sarasotasailing.org"],
    "allowedEvents": null,
    "views": ["results", "standings"],
    "theme": {
      "primaryColor": "#003366",
      "font": "Inter"
    }
  }'

Example Response

{
  "data": {
    "id": "embt_789",
    "name": "Club Website - Results Widget",
    "token": "emb_p9q0r1s2t3u4v5w6x7y8z9a0b1c2d3e4",
    "allowedOrigins": ["https://sarasotasailing.org"],
    "allowedEvents": null,
    "views": ["results", "standings"],
    "theme": {
      "primaryColor": "#003366",
      "font": "Inter"
    },
    "active": true,
    "createdAt": "2026-03-29T16:00:00Z"
  },
  "message": "Embed token created successfully"
}

Unlike API keys, the full token is always visible in list and get responses. Embed tokens are designed for client-side use.

Deactivate Embed Token

Deactivate an embed token. Deactivated tokens fail authentication immediately.

DELETE /api/v1/embed-tokens?id=:id

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The token ID to deactivate

Example Request

curl -X DELETE "https://rhumby.com/api/v1/embed-tokens?id=embt_789" \
  -H "Cookie: session=..."

Example Response

{
  "message": "Embed token deactivated"
}

Deactivating a token takes effect immediately. Widgets using that token will stop working on the next API call.

Each embed token grants access to specific widget types:

`standings`

Display real-time series or event standings with live scoring updates.

`results`

Show race results with finish times, corrected times, and individual race breakdowns.

`schedule`

List upcoming races with dates, times, courses, and race committee details.

`register`

Embed the full registration form, allowing sailors to sign up directly from your site.

Origin Restrictions

For security, always specify allowedOrigins in production:

{
  "allowedOrigins": [
    "https://yourdomain.com",
    "https://www.yourdomain.com"
  ]
}

The Rhumby API validates the Origin header on each request. Requests from unauthorized origins return 403 Forbidden.

Setting allowedOrigins: null allows any origin to use the token. Only use this for development or fully public widgets.

Theme Customization

Pass a custom theme object to match your site's branding:

{
  "theme": {
    "primaryColor": "#003366",
    "secondaryColor": "#FF6B35",
    "font": "Inter",
    "borderRadius": "8px",
    "darkMode": false
  }
}

See the Embed SDK Styling Guide for full theme options.

Best Practices

Security

Always set allowedOrigins in production to prevent unauthorized embedding.
Scope to specific events when possible using allowedEvents to limit data exposure.
Deactivate unused tokens to reduce attack surface.

Performance

Reuse tokens across multiple pages on the same domain instead of generating many tokens.
Cache tokens client-side to avoid fetching them on every page load.

Grant minimal views. Only enable widget types your site actually uses.
Use register carefully. Registration widgets can submit real registrations — ensure your audience is authorized.

Embed SDK Overview — How to integrate Rhumby widgets into your site
Widget Types — Detailed widget documentation
Token Management — Managing tokens in the web app
Styling Guide — Full theme customization reference

Embed Tokens

Embed tokens allow you to display Rhumby widgets (standings, results, schedules, registration) on external websites. Tokens scope widget access to specific events and origins.

Token Format

All embed tokens have the prefix emb_ followed by a URL-safe random string:

emb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Unlike API keys, embed tokens are not secret. They are designed to be embedded in public JavaScript and restrict access via allowed origins and event filters.

Endpoints

GET/api/v1/embed-tokens

List organization's embed tokens

POST/api/v1/embed-tokens

Create a new embed token

DELETE/api/v1/embed-tokens?id=:id

Deactivate an embed token

List Embed Tokens

Retrieve all embed tokens for a specific organization. Requires organization membership.

GET /api/v1/embed-tokens?organizationId=:orgId

Query Parameters

Parameter	Type	Required	Description
`organizationId`	`string`	Yes	UUID of the organization

Example Request

curl "https://rhumby.com/api/v1/embed-tokens?organizationId=org_abc123" \
  -H "Cookie: session=..."

This endpoint requires session authentication (logged in via web app). You must be an active member of the organization.

Example Response

{
  "data": [
    {
      "id": "embt_123",
      "name": "Club Website - Standings Widget",
      "token": "emb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "allowedOrigins": ["https://sarasotasailing.org", "https://www.sarasotasailing.org"],
      "allowedEvents": null,
      "views": ["standings", "schedule"],
      "theme": {
        "primaryColor": "#003366",
        "font": "Inter"
      },
      "active": true,
      "createdAt": "2026-01-10T09:00:00Z"
    },
    {
      "id": "embt_456",
      "name": "Friday Night Series Widget",
      "token": "emb_x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2",
      "allowedOrigins": null,
      "allowedEvents": ["evt_fridaynight2026"],
      "views": ["results", "standings"],
      "theme": null,
      "active": true,
      "createdAt": "2026-02-15T14:30:00Z"
    }
  ]
}

Parameter	Type	Required	Description
`id`	`string`	No	Unique token identifier
`name`	`string`	No	Human-readable token name
`token`	`string`	No	The embed token (prefixed with emb_)
`allowedOrigins`	`array`	No	Array of allowed origin URLs. Null means all origins allowed (not recommended for production).
`allowedEvents`	`array`	No	Array of event UUIDs this token can access. Null means all organization events.
`views`	`array`	No	Widget types enabled: "standings", "results", "schedule", "register"
`theme`	`object`	No	Custom theme overrides (colors, fonts, etc.). Null uses default theme.
`active`	`boolean`	No	Whether the token is active
`createdAt`	`string`	No	ISO 8601 timestamp of token creation

Create Embed Token

Generate a new embed token with specific widget permissions and origin restrictions.

POST /api/v1/embed-tokens

Request Body

Parameter	Type	Required	Description
`name`	`string`	Yes	Human-readable name for the token (max 100 characters)
`organizationId`	`string`	Yes	UUID of the organization this token belongs to
`allowedOrigins`	`array`	No	Array of allowed origin URLs. Omit or set to null to allow all origins (not recommended).
`allowedEvents`	`array`	No	Array of event UUIDs. Omit or set to null to allow all organization events.
`views`	`array`	Yes	Widget types to enable: "standings", "results", "schedule", "register"
`theme`	`object`	No	Custom theme object with primaryColor, secondaryColor, font, etc.

Example Request

curl -X POST "https://rhumby.com/api/v1/embed-tokens" \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Club Website - Results Widget",
    "organizationId": "org_abc123",
    "allowedOrigins": ["https://sarasotasailing.org"],
    "allowedEvents": null,
    "views": ["results", "standings"],
    "theme": {
      "primaryColor": "#003366",
      "font": "Inter"
    }
  }'

Example Response

{
  "data": {
    "id": "embt_789",
    "name": "Club Website - Results Widget",
    "token": "emb_p9q0r1s2t3u4v5w6x7y8z9a0b1c2d3e4",
    "allowedOrigins": ["https://sarasotasailing.org"],
    "allowedEvents": null,
    "views": ["results", "standings"],
    "theme": {
      "primaryColor": "#003366",
      "font": "Inter"
    },
    "active": true,
    "createdAt": "2026-03-29T16:00:00Z"
  },
  "message": "Embed token created successfully"
}

Unlike API keys, the full token is always visible in list and get responses. Embed tokens are designed for client-side use.

Deactivate Embed Token

Deactivate an embed token. Deactivated tokens fail authentication immediately.

DELETE /api/v1/embed-tokens?id=:id

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The token ID to deactivate

Example Request

curl -X DELETE "https://rhumby.com/api/v1/embed-tokens?id=embt_789" \
  -H "Cookie: session=..."

Example Response

{
  "message": "Embed token deactivated"
}

Deactivating a token takes effect immediately. Widgets using that token will stop working on the next API call.

Each embed token grants access to specific widget types:

`standings`

Display real-time series or event standings with live scoring updates.

`results`

Show race results with finish times, corrected times, and individual race breakdowns.

`schedule`

List upcoming races with dates, times, courses, and race committee details.

`register`

Embed the full registration form, allowing sailors to sign up directly from your site.

Origin Restrictions

For security, always specify allowedOrigins in production:

{
  "allowedOrigins": [
    "https://yourdomain.com",
    "https://www.yourdomain.com"
  ]
}

The Rhumby API validates the Origin header on each request. Requests from unauthorized origins return 403 Forbidden.

Setting allowedOrigins: null allows any origin to use the token. Only use this for development or fully public widgets.

Theme Customization

Pass a custom theme object to match your site's branding:

{
  "theme": {
    "primaryColor": "#003366",
    "secondaryColor": "#FF6B35",
    "font": "Inter",
    "borderRadius": "8px",
    "darkMode": false
  }
}

See the Embed SDK Styling Guide for full theme options.

Best Practices

Security

Always set allowedOrigins in production to prevent unauthorized embedding.
Scope to specific events when possible using allowedEvents to limit data exposure.
Deactivate unused tokens to reduce attack surface.

Performance

Reuse tokens across multiple pages on the same domain instead of generating many tokens.
Cache tokens client-side to avoid fetching them on every page load.

Grant minimal views. Only enable widget types your site actually uses.
Use register carefully. Registration widgets can submit real registrations — ensure your audience is authorized.

Embed SDK Overview — How to integrate Rhumby widgets into your site
Widget Types — Detailed widget documentation
Token Management — Managing tokens in the web app
Styling Guide — Full theme customization reference

Embed Tokens

On this page

Embed Tokens

On this page