Credentials

A credential is a named, encrypted secret that authorizes the platform to call an external service on your behalf.

A credential holds non-secret configuration (a client ID, a role ARN, an HMAC algorithm) alongside secret material (a token, a client secret) that the platform encrypts at rest with a KMS key and never returns in an API response. A credential is prefixed CRD_. Every credential has a credentialType that fixes which fields it carries and how it authenticates. Other resources reference a credential rather than embedding the secret. A connector binds a credential to each credential slot its catalog kind declares, and a webhook injects one into its URL, headers, or body through a Liquid {{ credential.<name> }} reference. An allowedUrlPatterns list on each credential restricts which outbound URLs may use it. A credential is scoped either to a single Space or, when spaceId is null, to the whole organization.

Variants

A credential comes in five variants, fixed at creation and determined by credentialType. Each type adds its own input and output fields to the base fields below.

credentialType	Authenticates by	Secret held
Text	A single opaque string injected verbatim, such as an API key or bearer token.	value
OAuth2ClientCredentials	The OAuth 2.0 client-credentials grant. The platform exchanges the client ID and secret for an access token.	clientSecret
OAuth2AuthorizationCode	The OAuth 2.0 authorization-code grant. A user completes a browser consent flow, and the platform stores and refreshes the resulting token.	clientSecret
AwsRole	Assuming an AWS IAM role by ARN with an external ID. No long-lived secret is stored.	None
HmacSignature	Signing the outbound request body with a shared secret. Used by webhooks to prove authenticity to the receiver.	secret

How credentials are referenced

A referencing resource never copies a credential. It points at the credential, and the platform resolves the secret at run time.

• A connector declares one credential slot per authentication input its catalog kind requires. The connector config maps each slot ID to a credential resource ID (CRD_). At run time the platform resolves each slot to the referenced credential.
• A webhook references a credential by name in its Liquid templates as {{ credential.<name> }}, usable in the URL, any header value, or the body. Bracket notation ({{ credential["complex-name"] }}) covers names that are not valid identifiers. For an AwsRole or HmacSignature credential, the reference resolves to a placeholder that the platform replaces with a computed SigV4 authorization or HMAC signature over the final request.

In both cases the platform enforces the credential's allowedUrlPatterns against the target URL before it uses the secret.

Inputs

Every credential accepts these fields regardless of type.

Field	Type	Required	Description
name	string	Required	Credential name. Must be a valid identifier (letters, digits, underscores, not starting with a digit) so it can be referenced as {{ credential.<name> }}.
credentialType	enum	Required	One of Text, OAuth2ClientCredentials, OAuth2AuthorizationCode, AwsRole, HmacSignature. Fixes which type-specific fields apply. Cannot change after creation.
description	string	Optional	Free-text description.
allowedUrlPatterns	array<string>	Required	Outbound URLs this credential may be sent to. Each entry is a domain (*.example.com), a host and path glob (api.example.com/v1/*/cases), or an https URL with a path prefix ending in a slash and *. An empty list makes the credential unusable.
spaceId	string	Optional	The Space the credential belongs to, prefixed SPC_. Null scopes it to the whole organization.

Secret fields are write-only. The API accepts them on create and update but never returns them. Omit a secret field on update to keep the stored value.

Text

A Text credential injects one string verbatim wherever it is referenced.

Field	Type	Required	Description
value	string	Required	The secret string, such as an API key or bearer token. Write-only, never returned.

OAuth2ClientCredentials

An OAuth2ClientCredentials credential runs the client-credentials grant to obtain an access token for a service-to-service call.

Field	Type	Required	Description
tokenUrl	string	Required	The token endpoint the platform posts to for an access token. Must be a URL.
clientId	string	Required	The OAuth client identifier.
clientSecret	string	Required	The OAuth client secret. Write-only, never returned.
scopes	string	Optional	Space-separated scopes requested with the token.
audience	string	Optional	The audience parameter sent to the token endpoint.

OAuth2AuthorizationCode

An OAuth2AuthorizationCode credential runs the authorization-code grant. A user completes a browser consent flow through the platform, which then stores and refreshes the token.

Field	Type	Required	Description
authorizationUrl	string	Required	The provider authorization endpoint the platform sends the user to for consent. Must be a URL.
tokenUrl	string	Required	The token endpoint the platform exchanges the authorization code at. Must be a URL.
clientId	string	Required	The OAuth client identifier.
clientSecret	string	Required	The OAuth client secret. Write-only, never returned.
scopes	string	Optional	Space-separated scopes requested for the application.
userScopes	string	Optional	Space-separated scopes requested on behalf of the connecting user.

AwsRole

An AwsRole credential assumes an AWS IAM role. No long-lived secret is stored.

Field	Type	Required	Description
roleArn	string	Required	The IAM role ARN to assume. Must match arn:aws:iam::<account-id>:role/<name>.
externalId	string	Required	Opaque string matched against the role trust policy external ID.
region	string	Optional	The AWS region to operate in. Defaults to the caller's region.

HmacSignature

An HmacSignature credential signs an outbound webhook request so the receiver can verify it. The signature replaces the header value the webhook template marks with this credential.

Field	Type	Required	Description
secret	string	Required	The shared signing secret. Write-only, never returned.
algorithm	enum	Optional	Hash algorithm: sha1, sha256, or sha512. Default sha256.
signatureFormat	enum	Optional	Encoding of the signature: hex or base64. Default hex.
includeTimestamp	boolean	Optional	Whether to send a timestamp header and include it in the signed payload.
timestampHeader	string	Optional	Header name carrying the timestamp when includeTimestamp is true. Default X-Webhook-Timestamp.

Outputs

Every credential returns the fields above except write-only secrets, which the API never returns.

Plus the common resource fields.

OAuth2AuthorizationCode

OAuth2AuthorizationCode returns these additional fields, which track the consent flow and have no input counterpart.

Field	Type	Description
redirectUri	string	The platform callback URL to register with the provider.
connectionStatus	enum	Consent-flow state: pending, connected, or error.
connectedAt	timestamp	When the credential last completed consent. Null before the first connection.
connectionError	string	The error message when connectionStatus is error. Null otherwise.

Related

• Connectors, which bind a credential to each authentication slot.
• Webhooks, which inject a credential through a Liquid reference.
• OAuth, the personal OAuth clients and connections used for authorization-code flows.
• Spaces, the scope a credential can be assigned to.
• Route signals to Slack, Jira, or PagerDuty, how to wire a credential into a webhook.