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

# Get the current account

> The account behind your token, and the three server-managed secrets that live on it.

The [account](/docs/) is the top of the tree: it holds your workspaces, profiles, and API keys, and billing lives here. This endpoint returns the account your token belongs to, and it is the one place three account-level secrets are exposed.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const account = await client.account.retrieve();

  console.log(account.metadata.name);
  console.log(account.spec.billingEmail);
  ```

  ```go Go theme={null}
  account, err := client.Account.Get(ctx)
  if err != nil {
  	panic(err.Error())
  }

  fmt.Println(account.Metadata.Name)
  fmt.Println(account.Spec.BillingEmail)
  ```

  ```ruby Ruby theme={null}
  account = cadenya.account.retrieve

  puts account.metadata.name
  puts account.spec.billing_email
  ```

  ```bash cURL theme={null}
  curl "https://api.cadenya.com/v1/account" \
    -H "Authorization: Bearer ${CADENYA_API_KEY}"
  ```
</CodeGroup>

It is account-scoped, so there is no `workspaceId` in the path. `spec` carries `billingEmail`, `description`, `domain`, and the list of `workspaces`.

## The three secrets in `info`

`info` holds credentials the server manages for you. Handle the response like a secret: it is the only read that exposes these.

### `webhookEventsHmacSecret`

The key that signs every [webhook](/docs/guides/webhooks) Cadenya sends, in [Standard Webhooks](https://www.standardwebhooks.com/) `wh_...` format. This is what you verify an incoming signature against, so a webhook handler reads it once at setup and stores it in your own secret manager.

```typescript theme={null}
const { webhookEventsHmacSecret } = (await client.account.retrieve()).info;
// Verify inbound webhooks against this. Do not log it.
```

Rotate it with `client.account.rotateWebhookSigningKey()`. The rotation response carries the new value once; update your verifier before you rotate, or in-flight deliveries fail their signature check.

### `globalApiKey`

The API key auto-provisioned with the account. `spec.token` is returned on **every** `GetAccount` call, so this endpoint is how you retrieve the global key whenever you need it, not only once.

```typescript theme={null}
const { globalApiKey } = (await client.account.retrieve()).info;
// globalApiKey.spec.token is a usable, account-scoped bearer JWT. Handle it like any credential.
```

Because a read hands back a working credential, treat the whole `GetAccount` response as secret-bearing: do not log it, and scope who can call it. Rotate the key to invalidate the old value.

### `challengeToken`

The token Cadenya sends in the `X-Cadenya-Challenge-Token` header on every MCP `tools/list` request. An MCP server can accept a valid challenge token in place of per-user auth when listing tools, while still requiring real auth on `tools/call`. Rotate with `client.account.rotateChallengeToken()`, and update any server validating it **before** you rotate, or its `tools/list` starts rejecting Cadenya.

## Rotate before you break

Each secret has a rotate endpoint, and each rotation is a cutover: the old value stops working the moment the new one is minted. The safe order is the same for all three.

1. Rotate, and capture the new value from the response.
2. Update the consumer (your webhook verifier, your MCP server, your stored key).
3. Confirm the consumer accepts the new value.

Do it in the other order and you get a window where signatures fail or `tools/list` is rejected.

<Warning>
  For the **webhook HMAC secret** and the **challenge token**, the rotate response is the only place the new value appears. `GetAccount` shows those two exist, not their values. Capture them from the rotate call. The **global API key** is the exception: `GetAccount` returns its token on every read, so you can always fetch it back.
</Warning>

## Identity versus account

`GetAccount` tells you which account. [`/v1/whoami`](/docs/api-reference/profilesservice/retrieves-the-profile-for-the-credentials-accessing-the-api) tells you which profile is holding the token inside it, and [`/v1/workspaces`](/docs/api-reference/workspaceservice/list-workspaces) tells you which workspaces that identity can reach. The three together are the whole "who am I and what can I touch" picture.

## Related

<CardGroup cols={2}>
  <Card title="Webhooks" icon="bell" href="/docs/guides/webhooks">
    Verifying a signature against `webhookEventsHmacSecret`.
  </Card>

  <Card title="Rotate the webhook signing key" icon="rotate" href="/docs/api-reference/accountservice/rotates-the-webhook-signing-key-for-the-account">
    Mint a new HMAC secret, and the cutover to plan around.
  </Card>

  <Card title="List workspaces" icon="list" href="/docs/api-reference/workspaceservice/list-workspaces">
    What the account's token can reach.
  </Card>

  <Card title="Get the current profile" icon="user" href="/docs/api-reference/profilesservice/retrieves-the-profile-for-the-credentials-accessing-the-api">
    The identity behind the token.
  </Card>
</CardGroup>


## OpenAPI

````yaml get /v1/account
openapi: 3.1.0
info:
  title: Cadenya API
  description: API for the Cadenya Agent Runtime platform.
  version: '1.0'
servers:
  - url: https://api.cadenya.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: AIProviderKeyService
  - name: APIKeyService
    description: |-
      Issue, rotate, disable, and revoke a workspace's API keys. Every key
       belongs to exactly one workspace; the system-managed global account key is
       managed via GlobalAPIKeyService instead.
  - name: AccountService
    description: >-
      Manage the authenticated account. Accounts are the top-level
      organizational
       unit and contain one or more workspaces.
  - name: AgentScheduleService
    description: >-
      Manage recurring schedules attached to agents. Schedules trigger
      objectives
       on a cadence defined by AgentScheduleSpec.Schedule.
  - name: AgentService
    description: >-
      Manage AI agents within a workspace. Agents define AI behavior and tool
      access.
  - name: AgentVariationService
    description: >-
      Manage variations of an agent and their tool, sub-agent, and memory layer
      assignments.
  - name: GlobalAPIKeyService
    description: |-
      Manage the account's system-provisioned global API key. The global key is
       the only key that spans every workspace; it is created by the system and
       cannot be deleted, so the surface is retrieve, rotate, and the
       disable/enable kill switch.
  - name: MemoryService
    description: >-
      Manage memory layers and their entries. Layers are named containers that
      can
       be composed into an objective's memory cascade; entries are the keyed values
       within a layer. System-managed layers (e.g., episodic layers created by the
       runtime) cannot be mutated through this API.
  - name: ModelService
    description: |-
      Manage LLM models available to a workspace. Models represent provider and
       family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
       with the supported models and you can enable or disable each one.
  - name: ObjectiveEventStreamsService
  - name: ObjectiveService
  - name: ProfilesService
    description: |-
      Operations on profiles, the account-level principals (users, API keys,
       system) that authenticate against the API.
  - name: SearchService
  - name: TenantService
    description: >-
      Read and erase tenants and the subjects under them. Tenants and subjects
      are
       created by assertion — on objective creation or widget session mint — never
       directly, so this service has no create or update: it exists to enumerate what
       assertions have produced, and to destroy it on request.
  - name: ToolService
    description: >-
      Manage tool sets and the tools they contain. Tool sets group related
      tools,
       and tools define specific capabilities available to agents.

       When a tool set is managed, only API key actors can modify its tools; human
       (profile) actors cannot.
  - name: UploadService
    description: |-
      Issue short-lived presigned URLs for direct client-to-object-storage
       uploads. Created uploads can be referenced by id when creating or updating
       resources that accept binary content (e.g., MemoryEntry).
  - name: WidgetService
    description: |-
      Manage embeddable chat widgets. A widget binds an agent to a globally
       unique hostname with a per-widget origin allowlist; browsers reach it with
       session tokens minted via WidgetSessionService.
  - name: WidgetSessionService
    description: >-
      Mint and manage widget sessions. Session creation is server-to-server
      only:
       the customer's backend authenticates its visitor, asserts tenant/subject
       context, attaches any per-visitor secrets, and receives a short-lived
       bearer token the browser uses against the widget host.
  - name: WorkspaceAdminService
    description: >-
      Administer workspaces across the account: create and archive workspaces
      and
       manage their membership. These operations are account-scoped and require the
       admin role (a token whose profile holds the WorkOS admin role); they live
       under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces
       tree so an admin can manage any workspace in the account, including ones they
       are not themselves a member of.
  - name: WorkspaceSecretService
  - name: WorkspaceService
    description: |-
      Manage workspaces within an account. Workspaces provide organizational
       grouping and isolation for resources such as agents, tools, and API keys.

       This is the workspace-scoped, end-user surface. Administrative operations
       (create / archive workspaces, manage members) live in WorkspaceAdminService
       under /v1/account/workspaces and require the admin role.
paths:
  /v1/account:
    get:
      tags:
        - AccountService
        - Accounts
      summary: Retrieves the current account for the token accessing the API
      description: >-
        Retrieves the current account for the token accessing the API. Useful to
        check if the credentials are valid.
      operationId: AccountService_GetAccount
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Cadenya from '@cadenya/cadenya';

            const client = new Cadenya({
              apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
            });

            const account = await client.account.retrieve();

            console.log(account.info);
        - lang: Python
          source: |-
            import os
            from cadenya import Cadenya

            client = Cadenya(
                api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
            )
            account = client.account.retrieve()
            print(account.info)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\taccount, err := client.Account.Get(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", account.Info)\n}\n"
        - lang: Ruby
          source: |-
            require "cadenya"

            cadenya = Cadenya::Client.new(api_key: "My API Key")

            account = cadenya.account.retrieve

            puts(account)
        - lang: CLI
          source: |-
            cadenya account retrieve \
              --api-key 'My API Key'
components:
  schemas:
    Account:
      required:
        - metadata
        - spec
        - info
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/AccountResourceMetadata'
        spec:
          $ref: '#/components/schemas/AccountSpec'
        info:
          $ref: '#/components/schemas/AccountInfo'
      description: |-
        An account, the top-level organizational unit. Contains workspaces and
         account-wide settings such as the webhook signing secret.
    Status:
      type: object
      properties:
        code:
          type: integer
          description: >-
            The status code, which should be an enum value of
            [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: >-
            A developer-facing error message, which should be in English. Any
            user-facing error message should be localized and sent in the
            [google.rpc.Status.details][google.rpc.Status.details] field, or
            localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: >-
            A list of messages that carry the error details.  There is a common
            set of message types for APIs to use.
      description: >-
        The `Status` type defines a logical error model that is suitable for
        different programming environments, including REST APIs and RPC APIs. It
        is used by [gRPC](https://github.com/grpc). Each `Status` message
        contains three pieces of data: error code, error message, and error
        details. You can find out more about this error model and how to work
        with it in the [API Design
        Guide](https://cloud.google.com/apis/design/errors).
    AccountResourceMetadata:
      required:
        - id
        - accountId
        - name
        - profileId
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: >-
            Unique identifier for the resource (prefixed ULID, e.g.,
            "apikey_01HXK...")
        accountId:
          readOnly: true
          example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
          type: string
          description: >-
            Account this resource belongs to for multi-tenant isolation
            (prefixed ULID)
        name:
          type: string
          description: >-
            Human-readable name for the resource (e.g., "Customer Support
            Agent", "Email Tool")
             Required for resources that users interact with directly
        externalId:
          type: string
          description: >-
            External ID for the resource (e.g., a workflow ID from an external
            system)
        labels:
          type: object
          additionalProperties:
            type: string
          description: |-
            Key-value pairs for categorization and filtering. Values are 0-63
             alphanumeric characters with "-", "_", or "." allowed between; keys
             follow the same shape and additionally accept an optional DNS-subdomain
             prefix (e.g. "cadenya.com/") of at most 253 characters.
             Examples: {"environment": "production", "team": "platform", "version": "v2"}
        profileId:
          readOnly: true
          example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
          type: string
        createdAt:
          readOnly: true
          type: string
          format: date-time
      description: >-
        AccountResourceMetadata is used to represent a resource that is
        associated to an account but not to a workspace.
    AccountSpec:
      type: object
      properties:
        description:
          type: string
        domain:
          type: string
        billingEmail:
          type: string
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/Workspace'
      description: Configuration for an account.
    AccountInfo:
      type: object
      properties:
        webhookEventsHmacSecret:
          readOnly: true
          type: string
          description: >-
            The generated secret that will sign all webhooks that are sent to
            your configured Webhook URL.
             Formatted as "wh_asdf1234" per the https://www.standardwebhooks.com/ format.
        challengeToken:
          readOnly: true
          type: string
          description: >-
            The challenge token Cadenya sends in the X-Cadenya-Challenge-Token
            header
             on every MCP tools/list request. Server implementations can accept a valid
             challenge token in place of per-user auth when listing tools, while still
             requiring real auth on tools/call. Rotate with RotateChallengeToken; update
             any servers validating the token before rotating.
      description: Server-populated information about the account.
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: >-
        Contains an arbitrary serialized message along with a @type that
        describes the type of the serialized message.
    Workspace:
      required:
        - metadata
        - spec
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/AccountResourceMetadata'
        spec:
          $ref: '#/components/schemas/WorkspaceSpec'
        status:
          readOnly: true
          enum:
            - STATUS_ENABLED
            - STATUS_DISABLED
            - STATUS_ARCHIVED
          type: string
          description: |-
            Lifecycle status of the workspace. Archived workspaces reject all
             requests scoped to them. Server-populated.
          format: enum
        info:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/WorkspaceInfo'
          description: The workspace information
    WorkspaceSpec:
      type: object
      properties:
        description:
          type: string
    WorkspaceInfo:
      type: object
      properties:
        totalAvailableTools:
          type: integer
          format: int32
        totalMemoryEntries:
          type: integer
          format: int32
        totalAgents:
          type: integer
          format: int32
        totalAgentVariations:
          type: integer
          format: int32
      description: WorkspaceInfo returns counts
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````