Quickstart

This guide walks you through the complete flow to start using the Sphere API — from resolving your tenant via the Hub, to authenticating and making your first API call. All client traffic goes through the Traefik gateway, so you only need a single base URL for each sphere.

Before you begin, you need a tenant provisioned on a Sphere instance with admin credentials. If you do not have these yet, ask your platform administrator to create a tenant for you.

POSThttps://hub.example.com/api/v1/hub/resolve-login

Step 1: Resolve your login via the Hub

The Hub is the discovery service. Given a user login (email), it returns the Sphere instance URL where that user's tenant lives. This is always the first step — you need the sphere URL before you can authenticate.

Request body

  • Name
    login
    Type
    string
    Description

    The email address of the user you want to authenticate. The Hub uses this to resolve which sphere instance hosts the tenant.

Response

The Hub returns the sphere URL and basic tenant information. Use the sphere_url to construct all subsequent API calls.

POST
/api/v1/hub/resolve-login
curl -X POST https://hub.example.com/api/v1/hub/resolve-login \
  -H "Content-Type: application/json" \
  -d '{"login": "admin@acme.local"}'

Response

{
  "sphere_url": "https://your-sphere.example.com",
  "tenant": {
    "name": "Acme Corp",
    "slug": "acme"
  }
}
POST/auth/api/v1/auth/login

Step 2: Authenticate and get a JWT token

Once you have the sphere URL from Step 1, send a login request to sphere-auth. A successful login returns an access_token (JWT RS256), a refresh_token, and a meta.services object that lists all available service endpoints for the tenant.

Request body

  • Name
    login
    Type
    string
    Description

    The user's email address.

  • Name
    password
    Type
    string
    Description

    The user's password.

Response

The response includes JWT tokens and the services discovery map. The access_token is valid for 60 minutes. The refresh_token is valid for 30 days.

The meta.services object is only returned in the login response. Subsequent calls to /auth/api/v1/auth/user do not include it, so store it after login.

POST
/auth/api/v1/auth/login
curl -X POST https://your-sphere.example.com/auth/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login": "admin@acme.local", "password": "SecurePass123!"}'

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "def50200a1b2c3d4...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "meta": {
    "services": {
      "core": "/core/api/v1",
      "chat": "/chat/api/v1",
      "voip": "/voip/api/v1",
      "drive": "/drive/api/v1",
      "activity": "/activity/api/v1",
      "usermanager": "/usermanager/api/v1",
      "notes": "/notes/api/v1",
      "mail": "/mail/api/v1"
    }
  }
}
GET/core/api/v1/families

Step 3: Make your first API call

With your access_token, you can now call any service endpoint. All requests go through the Traefik gateway using path-based routing — the gateway strips the service prefix and forwards the request to the correct backend.

Include the token in the Authorization header as a Bearer token.

In this example, we list all entity families defined in the tenant. Families define the schema (attributes, types) for your data model.

GET
/core/api/v1/families
curl https://your-sphere.example.com/core/api/v1/families \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "data": [
    {
      "id": "f1a2b3c4-...",
      "code": "contact",
      "label": "Contact",
      "attributes": [...]
    },
    {
      "id": "e5f6a7b8-...",
      "code": "company",
      "label": "Company",
      "attributes": [...]
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 50,
    "total": 2
  }
}
POST/auth/api/v1/auth/refresh

Step 4: Refresh your token

The access_token expires after 60 minutes. When it does, use the refresh_token to obtain a new pair of tokens without requiring the user to log in again.

Request body

  • Name
    refresh_token
    Type
    string
    Description

    The refresh token received during login or a previous refresh.

The response has the same structure as the login response but without the meta.services object.

POST
/auth/api/v1/auth/refresh
curl -X POST https://your-sphere.example.com/auth/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "def50200a1b2c3d4..."}'

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "def50200x9y8z7w6...",
  "token_type": "Bearer",
  "expires_in": 3600
}

What's next?

You are now set up to interact with the Sphere API. Here are some useful next steps:

Was this page helpful?