# Get the enterprise SSO status of a workspace

Needs workspace:settings:view.

`GET /api/v1/public/workspaces/workspaceId/enterprise`

- Sign-in: A signed-in user's session: send the session id in the x-session-id header.
- Rate limit: Up to 500 requests every 3 seconds per IP address; up to 1,000 requests a minute per API key (some requests are not counted).

Needs `workspace:settings:view`. Returns the company bound to this workspace (its sign-in connections, directory provisioning, certificate, domains, audit log setting, IT contacts and the groups the caller manages) and what the caller may do, area by area. Answers 404 `{ available: false }` when no enterprise is bound; `?refresh=1` re-reads the connections from the app owner's WorkOS account.

## Request

| Field         | Type   | Required | Constraints | Description |
| ------------- | ------ | -------- | ----------- | ----------- |
| `workspaceId` | string | Yes      | -           | -           |

## Example request

Replace each `YOUR_...` value with your own, and set the credential in the environment variable the sample reads.

```bash title="cURL"
curl -X GET "https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/enterprise" \
  -H "x-session-id: $BUILDBASE_SESSION_ID"
```

```ts title="TypeScript"
const response = await fetch(
  'https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/enterprise',
  {
    method: 'GET',
    headers: {
      'x-session-id': process.env.BUILDBASE_SESSION_ID ?? '',
    },
  }
);
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}
const data = await response.json();
```

```python title="Python"
import os

import requests

response = requests.get(
    "https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/enterprise",
    headers={
        "x-session-id": os.environ["BUILDBASE_SESSION_ID"],
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
```

## Responses

### 200 OK

OK

```json title="Example"
{
  "access": {
    "activity": "view",
    "admins": "manage",
    "apps": "manage",
    "groups": "manage",
    "insights": "view",
    "keys": "[REDACTED]",
    "people": "manage",
    "policy": "manage",
    "setup": "manage",
    "streams": "manage"
  },
  "admins": {
    "named": true,
    "you": true
  },
  "auditLogs": {
    "enabled": false,
    "retentionDays": null
  },
  "available": true,
  "canManage": true,
  "certificate": null,
  "domains": [
    {
      "domain": "it-contacts-1767225600000.test",
      "lastError": null,
      "source": "workos",
      "status": "verified",
      "verifiedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "enterprise": {
    "name": "Globex"
  },
  "groupsManaged": [],
  "itContacts": {
    "contacts": [
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "e9a8b97a49e8d3d6"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "2a350d9bfd0dd841"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "f87084c4e185ea32"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "0c00cabe03d041b9"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "68844f9033aa872d"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "50d976ef9cf4e973"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "7d5c032e2b12da06"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "8c832cd42a2f2bd1"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "8ada6bed298ec4ca"
      },
      {
        "addedAt": "2026-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "ref": "18ee2638333b383b"
      }
    ],
    "error": null,
    "max": 20,
    "readAt": "2026-01-01T00:00:00.000Z"
  },
  "provisioning": {
    "enabled": false,
    "lastSyncAt": null,
    "linked": false,
    "state": null
  },
  "role": "company-admin",
  "sso": {
    "beyondLimit": 0,
    "checkedAt": "2026-01-01T00:00:00.000Z",
    "connectionState": "active",
    "connections": [
      {
        "certificate": null,
        "domains": ["it-contacts-1767225600000.test"],
        "isDefault": true,
        "label": "Okta",
        "provider": "okta",
        "ref": "96ccc66c4a5e07f3",
        "state": "active",
        "type": "OktaSAML"
      }
    ],
    "limits": {
      "connections": 10,
      "labelMax": 60,
      "perDomain": 5,
      "routes": 50
    },
    "routing": {
      "confirmed": true,
      "defaultRef": "96ccc66c4a5e07f3",
      "routes": [],
      "unservedDomains": [],
      "updatedAt": null,
      "updatedBy": null,
      "version": 0
    }
  },
  "workosRoles": {
    "enabled": false,
    "readAt": null,
    "state": "off"
  }
}
```

### Any other status

Any other answer the handler sends itself (its own refusals). Not described yet.

## Errors

Each refusal, what it means, and what to do. The request changed nothing.

### 401 Unauthorized

**What it means:** The credential is missing, expired or not accepted here, or the caller's role has no grant for `x-permission` (refused with 401 too). The body is the plain text `Unauthorized`, or a JSON body with a `code` where the gate says why.

**What to do:** Send the credential this operation asks for (see Sign-in above), or sign in again if it expired. A valid credential is also refused when the role has no grant for the permission above.

```text title="Example"
Unauthorized
```

### 429 Too Many Requests

**What it means:** A rate limit in `x-rateLimit` was reached. `retryAfter` and the `Retry-After` header say how many seconds until the window resets.

**What to do:** Wait the number of seconds in the `Retry-After` header (also `retryAfter` in the body), then retry. Slow down repeated calls.

```json title="Example"
{
  "success": false,
  "message": "string",
  "reason": "rate_limited",
  "retryAfter": 1
}
```

## Related

- [Workspaces guide](/workspaces/overview): how this part of BuildBase works
- [All Workspaces operations](/http-api/reference/workspaces)
- [API reference](/http-api/reference): every operation, by tag
- [Sign-in and credentials for the HTTP API](/http-api/authentication)
- [How the HTTP API reports errors](/http-api/errors)
- [Make your first call](/http-api/first-call)
- [Error codes](/reference/error-codes): every `code` the API returns
- OpenAPI: operation `workspaces.enterprise.list` in [public-v1.json](https://docs.buildbase.app/openapi/public-v1.json)
