Stored and linked credentials

A stored credential holds the sign-in a job uses to reach a third-party app: a linked account a user connected, a secret supplied directly, or an organization service account. Use these V3Client methods to list, store, link, rename, check, and disconnect them. In the web app, users manage the same credentials under Linked Accounts. To bind a credential to a job, see Connected resources.

The secret is sealed at rest and never returned. Calls that return a credential return a CredentialDto without it; the other return types are named under each method. CredentialDto fields: id, name, auth_type (FunctionAuthType: jwt, token, basic, oauth1, oauth2, cas_delegated_3dx), status (CredentialStatus: active, revoked, expired), tenant_id, owner_user_id (None for an org-owned credential), auth_integration_id, account_identity, control_tags, created, created_by_id.

Anyone in the tenant can list and view its org-owned credentials (service accounts shared across the tenant). Creating, renaming, or disconnecting one needs a customer admin. Renaming or disconnecting a personal credential needs edit permission on it.

The Client equivalents are on Credentials.

List and get

list_stored_credentials()

Lists the credentials the caller can view: their own plus the tenant's org-owned service accounts, newest first. Revoked credentials are hidden; expired ones are listed so they can be re-linked.

• Parameters:

  • cursor (str, optional) – The previous page's next_page. Omit for the first page.
  • size (int, optional) – Page size, 0–100. The server returns 50 when omitted.
  • include_total (bool, optional) – Set False to skip the count.
  • auth_integration_id (list of str, optional) – Only credentials for these auth integrations. Supports the ! negation prefix.
  • http_request_timeout_secs (int, optional)

• Return Type: CursorPageCredentialDto

page = client.list_stored_credentials(size=50)
active = [c for c in page.items if c.status == "active"]

get_stored_credential()

Returns one credential the caller can view.

• Parameters:

  • credential_id (str) – (required)
  • http_request_timeout_secs (int, optional)

• Return Type: CredentialDto

Store a secret

create_stored_credential()

Stores a credential from a secret you supply, such as a username and password for a basic integration or an API token. OIDC and OAuth 1.0a credentials are created with the browser link instead. Returns 409 when an active credential for the same account already exists on the auth integration.

• Parameters:

  • credential_create_dto (CredentialCreateDto) – (required). Required: name, auth_type (FunctionAuthType), secret_value (the plaintext secret: password JSON, API key, or token). Optional: auth_integration_id, account_identity (max 255 characters), org_owned (default False).
  • http_request_timeout_secs (int, optional)

• Return Type: CredentialDto

from istari_digital_client.v3.models import CredentialCreateDto

credential = client.create_stored_credential(
    CredentialCreateDto(
        name="Build server token",
        auth_type="token",
        secret_value="{token}",
    )
)

create_service_connection_credential()

Creates an org-owned connection for an OAuth 1.0a integration with no browser authorization. Jobs sign with the integration's consumer key and secret alone and act as the service identity the provider's administrator associated with that consumer. Customer admins only.

• Parameters:

  • service_connection_create_dto (ServiceConnectionCreateDto) – (required). Required: auth_integration_id. Optional: name (max 255 characters).
  • http_request_timeout_secs (int, optional)

• Return Type: CredentialDto

Link an account in a browser

OIDC and OAuth 1.0a accounts are linked through the provider's authorization page, in two calls:

1. Call begin_link_credential() with the auth integration and the redirect_uri the provider should return to. The platform generates and holds the link's server-side material (the CSRF state and PKCE verifier, or the OAuth 1.0a request-token pair) and returns the provider's authorization url and an opaque handle.
2. Send the user's browser to url. After they approve, the provider redirects to redirect_uri with its proof of approval and a correlation value.
3. Call complete_link_credential() with the handle and those two values. The platform exchanges them for the secret and stores it; the secret never reaches the browser.

A provider that rejects the exchange returns 502.

begin_link_credential()

Starts a browser link against an auth integration.

• Parameters:

  • begin_link_dto (BeginLinkDto) – (required). auth_integration_id and redirect_uri, both required.
  • http_request_timeout_secs (int, optional)

• Return Type: BeginLinkResultDto — url (the provider authorization URL) and handle (pass it to complete_link_credential()).

complete_link_credential()

Completes the link after the provider redirects back. Pass reconnect_credential_id to refresh an existing credential: it is resealed in place even when the provider reports no account identity. A new credential returns HTTP 201; a reconnect, or a re-link of the same account, reseals the existing credential and returns 200. Both return the credential.

• Parameters:

  • complete_link_dto (CompleteLinkDto) – (required).
    • handle (required) — from begin_link_credential().
    • code (required) — the OIDC authorization code, or the OAuth 1.0a oauth_verifier.
    • state (required) — the OIDC state, or the OAuth 1.0a oauth_token.
    • name (optional, max 255 characters), org_owned (default False; customer admins only), reconnect_credential_id (optional).
  • http_request_timeout_secs (int, optional)

• Return Type: CredentialDto

from istari_digital_client.v3.models import BeginLinkDto, CompleteLinkDto

link = client.begin_link_credential(
    BeginLinkDto(
        auth_integration_id="{auth_integration_id}",
        redirect_uri="{redirect_uri}",
    )
)
print("Open in a browser:", link.url)

# After the provider redirects to {redirect_uri}, read code and state from its query string.
credential = client.complete_link_credential(
    CompleteLinkDto(handle=link.handle, code="{code}", state="{state}")
)

Update and validate

update_stored_credential()

Renames a credential. The captured account identity is unchanged.

• Parameters:

  • credential_id (str) – (required)
  • credential_update_dto (CredentialUpdateDto) – (required). name.
  • http_request_timeout_secs (int, optional)

• Return Type: CredentialDto

validate_stored_credential()

Checks whether the credential still works against its provider: a refresh-grant dry run for OIDC, or a signed identity request for OAuth 1.0a. A definitive rejection marks the credential expired, so you can prompt a re-link before launching a job. A transient failure changes nothing.

• Parameters:

  • credential_id (str) – (required)
  • http_request_timeout_secs (int, optional)

• Return Type: CredentialValidationDto — status after the probe, checked (false when the credential kind has no probe or the provider could not be reached; status is then unchanged), and detail.

Disconnect

delete_stored_credential()

Revokes the credential and scrubs its secret. Jobs bound to it afterwards fail until the account is linked again.

• Parameters:

  • credential_id (str) – (required)
  • http_request_timeout_secs (int, optional)

• Return Type: None