Signing Session: Roles, Caps, and Identity Payload

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).

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

Request

GET /v1/signing/session

No query parameters. No request body.

curl https://api.safeclose.com/v1/signing/session \
  -H "Authorization: Bearer <clerk_jwt>"

Response

Returns a SigningSessionJson object.

string

required

Your Clerk user ID (sub claim from the JWT). This is the primary key used to look up all signing identity rows.

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.

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.

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.

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.

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.

Show properties

AccessTierJson

required

Access tier for the signings module. One of "none", "read", "write", or "full".

AccessTierJson

required

Access tier for the templates module.

AccessTierJson

required

Access tier for the flows module.

AccessTierJson

required

Access tier for the reports module.

AccessTierJson

required

Access tier for the settings module.

SigningVaultCapsJson

required

Boolean capability flags for vault operations. See Vault capabilities below.

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.

object

required

Flattened capability object designed for fast client-side guards. Duplicates some information from managerModules/adminModules but avoids conditional null-checks.

Show properties

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).

boolean

required

Whether you may call GET /v1/signing/organizations.

boolean

required

Whether you may call GET /v1/signing/companies.

boolean

required

Whether you may call GET /v1/signing/signer/signings and related signer-scoped endpoints. Requires at least one linked signer row.

ManagerModuleCapsJson or null

Same object as the top-level managerModules field. Included here for convenience so clients can access all caps from one object.

ManagerModuleCapsJson or null

Same object as the top-level adminModules field.

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

{
  "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
  }
}

{
  "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
      }
    }
  }
}

Overview

Documents

Signing

Workspace

Signing Session: Roles, Caps, and Identity Payload

Request

Response

Access tier values

Vault capabilities

Error responses

Example response

​Request

​Response

​Access tier values

​Vault capabilities

​Error responses

​Example response

Request

Response

Access tier values

Vault capabilities

Error responses

Example response