Organizations

This section applies to partner accounts (please get in touch at partners@skillflare.co to request a partner account). A partner or platform API key can list organizations. Only a partner key can create or update a child. A client key receives 403.

Partners provision child organizations for their end clients. Each child has its own candidates, challenges, sessions, and evaluations. Auth: organization API key. Create and update always use the organization that owns the key. They ignore x-organization-id.

List

curl "https://api.skillflare.co/v1/organizations?limit=20&offset=0" \
  -H "x-api-key: sk_skillflare_YOUR_KEY"

Returns { data, meta } as described in Errors and pagination. The caller's organization is first, then each direct child by name:

{
  "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "name": "Northwind Agency",
  "slug": "northwind",
  "organization_tier": "CLIENT",
  "branding_config": {
    "logo_url": "https://cdn.example.com/logo.png",
    "primary_color": "#0F6E56",
    "sender_name": "Northwind Hiring",
    "sender_local_part": "hiring"
  },
  "created_at": "2026-10-21T12:00:00.000Z"
}

• organization_tier — PARTNER or PLATFORM for the key's organization, CLIENT for a child.
• name — organization name. This is the company name on candidate pages and invite emails. See Where branding is applied.
• slug — public tenant key. Candidates can load white-label branding from GET /v1/public/tenants/:slug.
• branding_config — optional logo_url (https), primary_color (#rrggbb), sender_name, and sender_local_part. See Where branding is applied.

Create a client organization

curl https://api.skillflare.co/v1/organizations \
  -H "x-api-key: sk_skillflare_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Northwind Agency",
    "slug": "northwind",
    "branding_config": {
      "logo_url": "https://cdn.example.com/logo.png",
      "primary_color": "#0F6E56",
      "sender_name": "Northwind Hiring",
      "sender_local_part": "hiring"
    }
  }'

name is required. slug and branding_config are optional. When slug is omitted, Skillflare assigns one from the name. The new organization is always a CLIENT whose parent is the partner that owns the API key. The response is the organization object with 201.

A duplicate slug returns 409 CONFLICT with message Slug is already in use.

Update a client organization

curl -X PATCH https://api.skillflare.co/v1/organizations/b1c2d3e4-f5a6-7890-abcd-ef1234567890 \
  -H "x-api-key: sk_skillflare_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Northwind Studio"
  }'

name, slug, and branding_config are the same fields as create. Send at least one. Omitted fields stay as they are. A branding_config object merges onto the stored branding: keys you send replace those keys, and keys you omit stay. organization_tier and the parent cannot be changed.

The child must be a direct child of the partner that owns the key. The response is the organization object with 200.

An id that is not a UUID returns 400. An unknown organization returns 404. The partner organization itself, or any organization that is not a direct child, returns 403. A slug already used by another organization returns 409 CONFLICT with message Slug is already in use.

Where branding is applied

name is the company name. branding_config holds logo_url (https), primary_color (#rrggbb), sender_name, and sender_local_part. A branding_config that includes company_name returns 400 VALIDATION_ERROR.

List, create, and update store branding_config and return it on the organization. Candidates, challenges, and sessions keep their own fields.

Candidates load branding without an API key:

curl https://api.skillflare.co/v1/public/tenants/northwind

x-tenant-key overrides the slug in the path. The response is:

{
  "slug": "northwind",
  "company_name": "Northwind Agency",
  "logo_url": "https://cdn.example.com/logo.png",
  "primary_color": "#0F6E56"
}

company_name is the organization name. The candidate lobby and screen use it as the logo alt text. The Skillflare wordmark stays in place until logo_url is set. primary_color sets the --brand-primary accent.

GET /v1/public/tenants/by-host?host=assess.northwind.example returns that object as branding, with organization_id and custom_domain. An unknown slug or host returns 404.

Creating a session queues an invite email for the active organization. The subject, body, footer, and logo alt use the organization name, then Skillflare. The From display name is sender_name, then that same display text. sender_local_part is the mailbox before @ on a verified sending domain (1-64 letters, digits, or . _ + -, stored lowercased).

Acting as a client organization

x-organization-id selects the organization for candidate, challenge, and session requests. Omit it to use the organization that owns the API key. A partner key may pass a direct client. Organization create and update ignore the header and always use the key's organization.

A row outside the selected organization is not found.

curl https://api.skillflare.co/v1/candidates \
  -H "x-api-key: sk_skillflare_YOUR_KEY" \
  -H "x-organization-id: CHILD_ORG_UUID" \
  -H "content-type: application/json" \
  -d '{
    "email": "alex@example.com",
    "full_name": "Alex Example"
  }'

The child must be a direct child of the partner that owns the key. Omit x-organization-id to act as the partner organization itself.

A non-empty organization_id in the query or body returns 400 VALIDATION_ERROR.

A key created for a child organization is scoped to that child alone. Create that key from the dashboard while the child is selected. There is no HTTP route for creating keys.