> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safeclose.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing Session: Roles, Caps, and Identity Payload

> Fetch your full signing identity in one call—manager and admin rows, signer assignments, resolved roles, module access tiers, and vault capability flags.

The session endpoint is the entry point for every signing integration. It returns a single JSON payload that encodes who you are in the Safeclose signing system—your manager row, admin row, signer rows, the module tiers granted to you through your role assignments, and a flat `caps` object you can use to gate UI and API calls without any additional round trips.

All requests to `/v1/signing/*` require a valid Clerk session JWT in the `Authorization: Bearer` header. The session endpoint itself returns `200` for any authenticated Clerk user, but returns `403` if that user has no linked signing identity (no manager, admin, or signer row with a matching `clerk_user_id`).

<Note>
  `GET /v1/signing/me` is a legacy alias for this endpoint. Both paths return the identical payload. Prefer `/v1/signing/session` in new integrations.
</Note>

## Request

```
GET /v1/signing/session
```

No query parameters. No request body.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/session \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

## Response

Returns a `SigningSessionJson` object.

<ResponseField name="userId" type="string" required>
  Your Clerk user ID (`sub` claim from the JWT). This is the primary key used to look up all signing identity rows.
</ResponseField>

<ResponseField name="manager" type="object or null">
  Your manager identity record, if one is linked to your account. Numeric ID fields are serialized as strings. `null` if you are not a manager.
</ResponseField>

<ResponseField name="admin" type="object or null">
  Your admin identity record, if one exists. `null` if you are not an admin. Admin accounts carry elevated read access across all organizations.
</ResponseField>

<ResponseField name="signers" type="array">
  All signer records linked to your account. A single user may be a signer on multiple packages. Empty array if you have no signer assignments.
</ResponseField>

<ResponseField name="resolvedRoles" type="array">
  Which roles you currently hold. Each element is one of `"manager"`, `"admin"`, or `"signer"`. A user may hold more than one role simultaneously—for example, a manager who is also assigned as a signer on a package.
</ResponseField>

<ResponseField name="managerModules" type="ManagerModuleCapsJson or null">
  Module access tiers derived by merging all roles assigned to you across your organization and location memberships. When you have access through multiple roles, the **maximum** tier per module wins, and vault booleans are OR-ed together. `null` if you are not a manager.

  <Expandable title="properties">
    <ResponseField name="signings" type="AccessTierJson" required>
      Access tier for the signings module. One of `"none"`, `"read"`, `"write"`, or `"full"`.
    </ResponseField>

    <ResponseField name="templates" type="AccessTierJson" required>
      Access tier for the templates module.
    </ResponseField>

    <ResponseField name="flows" type="AccessTierJson" required>
      Access tier for the flows module.
    </ResponseField>

    <ResponseField name="reports" type="AccessTierJson" required>
      Access tier for the reports module.
    </ResponseField>

    <ResponseField name="settings" type="AccessTierJson" required>
      Access tier for the settings module.
    </ResponseField>

    <ResponseField name="vault" type="SigningVaultCapsJson" required>
      Boolean capability flags for vault operations. See [Vault capabilities](#vault-capabilities) below.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="adminModules" type="ManagerModuleCapsJson or null">
  Fixed full-capability set for admin users (`"full"` on every tier, all vault booleans `true`). `null` if you are not an admin. The shape is identical to `managerModules`.
</ResponseField>

<ResponseField name="caps" type="object" required>
  Flattened capability object designed for fast client-side guards. Duplicates some information from `managerModules`/`adminModules` but avoids conditional null-checks.

  <Expandable title="properties">
    <ResponseField name="organizationScope" type="string" required>
      One of `"none"`, `"managed"`, or `"global"`. `"managed"` means you can only see organizations reachable through your employee memberships. `"global"` means you have admin-level read across all organizations (capped at 500 rows per list request).
    </ResponseField>

    <ResponseField name="canListOrganizations" type="boolean" required>
      Whether you may call `GET /v1/signing/organizations`.
    </ResponseField>

    <ResponseField name="canListCompanies" type="boolean" required>
      Whether you may call `GET /v1/signing/companies`.
    </ResponseField>

    <ResponseField name="canViewSignerAssignments" type="boolean" required>
      Whether you may call `GET /v1/signing/signer/signings` and related signer-scoped endpoints. Requires at least one linked signer row.
    </ResponseField>

    <ResponseField name="manager" type="ManagerModuleCapsJson or null">
      Same object as the top-level `managerModules` field. Included here for convenience so clients can access all caps from one object.
    </ResponseField>

    <ResponseField name="admin" type="ManagerModuleCapsJson or null">
      Same object as the top-level `adminModules` field.
    </ResponseField>
  </Expandable>
</ResponseField>

## Access tier values

| Value     | Meaning                                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------------------ |
| `"none"`  | No access to this module. Feature-level UI should be hidden.                                                 |
| `"read"`  | Read-only access. List and detail endpoints are permitted.                                                   |
| `"write"` | Read + mutation access. Create, update, cancel, and resend endpoints are permitted.                          |
| `"full"`  | Administrative or destructive operations (when implemented). Admins always receive `"full"` on every module. |

## Vault capabilities

All fields are `boolean`.

| Field                      | Description                                                |
| -------------------------- | ---------------------------------------------------------- |
| `shareDeal`                | May share a deal with another party.                       |
| `claimDeal`                | May claim an unclaimed deal.                               |
| `transferDeal`             | May transfer a deal to another organization.               |
| `transferDocuments`        | May transfer individual documents within a deal.           |
| `transferDealBack`         | May reverse a deal transfer.                               |
| `archiveDeal`              | May archive a completed deal.                              |
| `linkDeals`                | May link two related deals together.                       |
| `uploadDocuments`          | May upload new documents to a deal.                        |
| `replaceUploadedDocuments` | May replace previously uploaded documents.                 |
| `changeSettings`           | May change vault-level settings for a deal.                |
| `externDealDocsVideos`     | May share deal documents and videos with external parties. |
| `externCompanyLocations`   | May expose company location data externally.               |
| `externOrganizations`      | May expose organization data externally.                   |
| `exportSigningsList`       | May export the signings list.                              |

## Error responses

| Status | Condition                                                                        |
| ------ | -------------------------------------------------------------------------------- |
| `401`  | Missing or invalid Clerk JWT.                                                    |
| `403`  | Valid Clerk user but no manager, admin, or signer row is linked to this account. |

## Example response

<CodeGroup>
  ```json Full session (manager + signer) theme={null}
  {
    "userId": "user_2abc123XYZ",
    "manager": {
      "id": "42",
      "clerkUserId": "user_2abc123XYZ",
      "name": "Jordan Lee",
      "email": "jordan@dealership.com",
      "createdAt": "2025-01-15T09:00:00.000Z",
      "updatedAt": "2025-06-01T14:22:00.000Z"
    },
    "admin": null,
    "signers": [
      {
        "id": "801",
        "signingId": "3001",
        "clerkUserId": "user_2abc123XYZ",
        "status": "pending",
        "number": 1,
        "fullName": "Jordan Lee",
        "email": "jordan@dealership.com",
        "updatedAt": "2025-06-10T11:00:00.000Z"
      }
    ],
    "resolvedRoles": ["manager", "signer"],
    "managerModules": {
      "signings": "write",
      "templates": "read",
      "flows": "read",
      "reports": "none",
      "settings": "none",
      "vault": {
        "shareDeal": true,
        "claimDeal": false,
        "transferDeal": false,
        "transferDocuments": true,
        "transferDealBack": false,
        "archiveDeal": true,
        "linkDeals": false,
        "uploadDocuments": true,
        "replaceUploadedDocuments": false,
        "changeSettings": false,
        "externDealDocsVideos": false,
        "externCompanyLocations": false,
        "externOrganizations": false,
        "exportSigningsList": true
      }
    },
    "adminModules": null,
    "caps": {
      "organizationScope": "managed",
      "canListOrganizations": true,
      "canListCompanies": true,
      "canViewSignerAssignments": true,
      "manager": {
        "signings": "write",
        "templates": "read",
        "flows": "read",
        "reports": "none",
        "settings": "none",
        "vault": {
          "shareDeal": true,
          "claimDeal": false,
          "transferDeal": false,
          "transferDocuments": true,
          "transferDealBack": false,
          "archiveDeal": true,
          "linkDeals": false,
          "uploadDocuments": true,
          "replaceUploadedDocuments": false,
          "changeSettings": false,
          "externDealDocsVideos": false,
          "externCompanyLocations": false,
          "externOrganizations": false,
          "exportSigningsList": true
        }
      },
      "admin": null
    }
  }
  ```

  ```json Admin session theme={null}
  {
    "userId": "user_9zAdmin",
    "manager": null,
    "admin": {
      "id": "5",
      "clerkUserId": "user_9zAdmin",
      "email": "admin@safeclose.com",
      "createdAt": "2024-11-01T00:00:00.000Z",
      "updatedAt": "2025-05-20T08:00:00.000Z"
    },
    "signers": [],
    "resolvedRoles": ["admin"],
    "managerModules": null,
    "adminModules": {
      "signings": "full",
      "templates": "full",
      "flows": "full",
      "reports": "full",
      "settings": "full",
      "vault": {
        "shareDeal": true,
        "claimDeal": true,
        "transferDeal": true,
        "transferDocuments": true,
        "transferDealBack": true,
        "archiveDeal": true,
        "linkDeals": true,
        "uploadDocuments": true,
        "replaceUploadedDocuments": true,
        "changeSettings": true,
        "externDealDocsVideos": true,
        "externCompanyLocations": true,
        "externOrganizations": true,
        "exportSigningsList": true
      }
    },
    "caps": {
      "organizationScope": "global",
      "canListOrganizations": true,
      "canListCompanies": true,
      "canViewSignerAssignments": false,
      "manager": null,
      "admin": {
        "signings": "full",
        "templates": "full",
        "flows": "full",
        "reports": "full",
        "settings": "full",
        "vault": {
          "shareDeal": true,
          "claimDeal": true,
          "transferDeal": true,
          "transferDocuments": true,
          "transferDealBack": true,
          "archiveDeal": true,
          "linkDeals": true,
          "uploadDocuments": true,
          "replaceUploadedDocuments": true,
          "changeSettings": true,
          "externDealDocsVideos": true,
          "externCompanyLocations": true,
          "externOrganizations": true,
          "exportSigningsList": true
        }
      }
    }
  }
  ```
</CodeGroup>