API Keys

APIKey pydantic-model

Bases: BaseModel

Rowan API key.

Attributes:

Name	Type	Description
uuid	str	UUID of the API key
name	str	human-readable name of the API key
created_at	datetime	when the key was created
expires_at	datetime	when the key expires
is_expired	bool	whether the key has expired
is_revoked	bool	whether the key has been revoked
scope	str	permission scope ("read", "read_write", or "read_write_delete")
can_manage_api_keys	bool	whether this key can create/list/revoke other API keys
budget	float | None	maximum credits this key may spend. None means unlimited
credits_used	float	credits spent by this key so far
scoped_project_uuid	str | None	project to which access is restricted
created_by_key_uuid	str | None	UUID of the API key used to create this one (if any)
revoked_at	datetime | None	when the key was revoked, if applicable
last_used_at	datetime | None	when the key was last used, if known

Show JSON schema:

{
  "description": "Rowan API key.\n\nAttributes:\n    uuid: UUID of the API key\n    name: human-readable name of the API key\n    created_at: when the key was created\n    expires_at: when the key expires\n    is_expired: whether the key has expired\n    is_revoked: whether the key has been revoked\n    scope: permission scope (\"read\", \"read_write\", or \"read_write_delete\")\n    can_manage_api_keys: whether this key can create/list/revoke other API keys\n    budget: maximum credits this key may spend. `None` means unlimited\n    credits_used: credits spent by this key so far\n    scoped_project_uuid: project to which access is restricted\n    created_by_key_uuid: UUID of the API key used to create this one (if any)\n    revoked_at: when the key was revoked, if applicable\n    last_used_at: when the key was last used, if known",
  "properties": {
    "uuid": {
      "title": "Uuid",
      "type": "string"
    },
    "name": {
      "title": "Name",
      "type": "string"
    },
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "expires_at": {
      "format": "date-time",
      "title": "Expires At",
      "type": "string"
    },
    "is_expired": {
      "title": "Is Expired",
      "type": "boolean"
    },
    "is_revoked": {
      "title": "Is Revoked",
      "type": "boolean"
    },
    "scope": {
      "title": "Scope",
      "type": "string"
    },
    "can_manage_api_keys": {
      "title": "Can Manage Api Keys",
      "type": "boolean"
    },
    "budget": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Budget"
    },
    "credits_used": {
      "default": 0,
      "title": "Credits Used",
      "type": "number"
    },
    "scoped_project_uuid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scoped Project Uuid"
    },
    "created_by_key_uuid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Created By Key Uuid"
    },
    "revoked_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Revoked At"
    },
    "last_used_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Last Used At"
    }
  },
  "required": [
    "uuid",
    "name",
    "created_at",
    "expires_at",
    "is_expired",
    "is_revoked",
    "scope",
    "can_manage_api_keys"
  ],
  "title": "APIKey",
  "type": "object"
}

Fields:

• uuid (str)
• name (str)
• created_at (datetime)
• expires_at (datetime)
• is_expired (bool)
• is_revoked (bool)
• scope (str)
• can_manage_api_keys (bool)
• budget (float | None)
• credits_used (float)
• scoped_project_uuid (str | None)
• created_by_key_uuid (str | None)
• revoked_at (datetime | None)
• last_used_at (datetime | None)

revoke

revoke() -> Self

Revoke this API key.

Returns:

Type	Description
Self	updated APIKey object

refresh

refresh(in_place: bool = True) -> Self

Reload this key's metadata (e.g. credits_used) from the server.

Parameters:

Name	Type	Description	Default
in_place	bool	update this instance in place rather than return a new instance	True

Returns:

Type	Description
Self	updated APIKey object

Raises:

Type	Description
ValueError	this key is no longer present in the account's key list

CreatedAPIKey pydantic-model

Bases: BaseModel

Result of creating a new API key.

The plaintext key is only available at creation time – store it now, it cannot be retrieved later.

Attributes:

Name	Type	Description
key	str	plaintext API key. Save this; it is only returned once
api_key	APIKey	metadata for the newly-created key

Show JSON schema:

{
  "$defs": {
    "APIKey": {
      "description": "Rowan API key.\n\nAttributes:\n    uuid: UUID of the API key\n    name: human-readable name of the API key\n    created_at: when the key was created\n    expires_at: when the key expires\n    is_expired: whether the key has expired\n    is_revoked: whether the key has been revoked\n    scope: permission scope (\"read\", \"read_write\", or \"read_write_delete\")\n    can_manage_api_keys: whether this key can create/list/revoke other API keys\n    budget: maximum credits this key may spend. `None` means unlimited\n    credits_used: credits spent by this key so far\n    scoped_project_uuid: project to which access is restricted\n    created_by_key_uuid: UUID of the API key used to create this one (if any)\n    revoked_at: when the key was revoked, if applicable\n    last_used_at: when the key was last used, if known",
      "properties": {
        "uuid": {
          "title": "Uuid",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        },
        "created_at": {
          "format": "date-time",
          "title": "Created At",
          "type": "string"
        },
        "expires_at": {
          "format": "date-time",
          "title": "Expires At",
          "type": "string"
        },
        "is_expired": {
          "title": "Is Expired",
          "type": "boolean"
        },
        "is_revoked": {
          "title": "Is Revoked",
          "type": "boolean"
        },
        "scope": {
          "title": "Scope",
          "type": "string"
        },
        "can_manage_api_keys": {
          "title": "Can Manage Api Keys",
          "type": "boolean"
        },
        "budget": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Budget"
        },
        "credits_used": {
          "default": 0,
          "title": "Credits Used",
          "type": "number"
        },
        "scoped_project_uuid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Scoped Project Uuid"
        },
        "created_by_key_uuid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Created By Key Uuid"
        },
        "revoked_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Revoked At"
        },
        "last_used_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Last Used At"
        }
      },
      "required": [
        "uuid",
        "name",
        "created_at",
        "expires_at",
        "is_expired",
        "is_revoked",
        "scope",
        "can_manage_api_keys"
      ],
      "title": "APIKey",
      "type": "object"
    }
  },
  "description": "Result of creating a new API key.\n\nThe plaintext `key` is only available at creation time \u2013 store it now,\nit cannot be retrieved later.\n\nAttributes:\n    key: plaintext API key. Save this; it is only returned once\n    api_key: metadata for the newly-created key",
  "properties": {
    "key": {
      "title": "Key",
      "type": "string"
    },
    "api_key": {
      "$ref": "#/$defs/APIKey"
    }
  },
  "required": [
    "key",
    "api_key"
  ],
  "title": "CreatedAPIKey",
  "type": "object"
}

Fields:

• key (str)
• api_key (APIKey)

create_api_key

create_api_key(name: str = 'api-key', scope: APIKeyScope = 'read_write', valid_days: int = 365, scoped_project_uuid: str | None = None, budget: float | None = None) -> CreatedAPIKey

Create a new API key.

The caller must currently authenticate with an unscoped key that has can_manage_api_keys permission.

Parameters:

Name	Type	Description	Default
name	str	human-readable name for the key	'api-key'
scope	APIKeyScope	permission scope. One of "read", "read_write", "read_write_delete"	'read_write'
valid_days	int	number of days until the key expires	365
scoped_project_uuid	str | None	project to which access is restricted	None
budget	float | None	maximum credits the key may spend. If not provided, the key has no spending limit	None

Returns:

Type	Description
CreatedAPIKey	plaintext key together with its metadata; the plaintext key is
CreatedAPIKey	only returned once – store it immediately

list_api_keys

list_api_keys(active: bool | None = True) -> list[APIKey]

List API keys belonging to the current user.

Parameters:

Name	Type	Description	Default
active	bool | None	filter by key validity: True for non-revoked, non-expired keys, False for revoked or expired keys, or None for all keys	True

Returns:

Type	Description
list[APIKey]	matching API keys

revoke_api_key

revoke_api_key(uuid: str) -> APIKey

Revoke an API key by UUID.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the key to revoke	required

Returns:

Type	Description
APIKey	updated APIKey object

update_api_key_budget

update_api_key_budget(uuid: str, budget: float | None) -> APIKey

Update the spending budget of an API key.

The caller must currently authenticate with an unscoped key that has can_manage_api_keys permission.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the key to update	required
budget	float | None	new maximum credits the key may spend. Pass None to remove the spending limit	required

Returns:

Type	Description
APIKey	updated APIKey object

api_credentials

api_credentials(api_key: str, project_uuid: str | None = None, *, reveal_api_key: bool = True) -> Generator[None, None, None]

Temporarily use Rowan credentials in the current execution context.

Context-local credentials take precedence over module-level and environment configuration. Nested contexts restore the previous credentials when they exit, and concurrent threads or asynchronous tasks remain isolated from one another.

Parameters:

Name	Type	Description	Default
api_key	str	Rowan API key	required
project_uuid	str | None	active project UUID, if any	None
reveal_api_key	bool	whether get_api_key may reveal these credentials	True

Yields:

Type	Description
None	control while the credentials are active

Raises:

Type	Description
ValueError	API key is empty

get_api_key

get_api_key() -> str

Return the configured Rowan API key when it is visible in this context.