The oauth2Connection function creates an OAuth 2.0 connection definition. Prismatic handles the OAuth token exchange, refresh, and storage automatically. You choose between the Authorization Code flow (user-facing consent) and the Client Credentials flow (machine-to-machine).
Function signature function oauth2Connection < T extends OAuth2ConnectionDefinition >( definition : T ) : T
OAuth2ConnectionDefinition is a union of OAuth2AuthorizationCodeConnectionDefinition and OAuth2ClientCredentialConnectionDefinition. The required oauth2Type field discriminates the two.Parameters definition
OAuth2ConnectionDefinition
required
An object describing the OAuth 2.0 connection. Fields differ by oauth2Type.
Common fields Unique programmatic identifier for this connection type.
definition.display
ConnectionDisplayDefinition
required
Controls how this connection appears in the Prismatic UI. Show ConnectionDisplayDefinition fields
Describes this connection.
Path to avatar icon relative to the built component source.
display.icons.oauth2ConnectionIconPath
Path to icon for the OAuth “Connect” button.
Discriminates the flow type:
OAuth2Type.AuthorizationCode ("authorization_code") — three-legged flow with user consentOAuth2Type.ClientCredentials ("client_credentials") — two-legged machine-to-machine flow definition.oauth2Config
OAuth2Config & OAuth2UrlOverrides
Optional OAuth 2.0 configuration. oauth2Config.overrideGrantType
Overrides the grant_type parameter sent in the token request. Use for non-standard OAuth 2.0 servers.
oauth2Config.allowedTokenParams
Additional parameters to include in the token request.
oauth2Config.oAuthSuccessRedirectUri
Custom URI where users are sent after a successful OAuth authorization. See custom redirects . oauth2Config.oAuthFailureRedirectUri
Custom URI where users are sent after a failed OAuth authorization.
Authorization Code fields Required when oauth2Type is OAuth2Type.AuthorizationCode:
definition.inputs.authorizeUrl
The OAuth 2.0 authorization URL where users consent to granting access (e.g., https://app.acme.com/oauth2/authorize).
definition.inputs.tokenUrl
The OAuth 2.0 token URL for exchanging an authorization code or refresh token for an access token (e.g., https://app.acme.com/oauth2/token).
OAuth 2.0 permissions to request from the user.
definition.inputs.clientId
The OAuth 2.0 client ID (sometimes called app key).
definition.inputs.clientSecret
The OAuth 2.0 client secret (sometimes called app secret).
definition.oauth2PkceMethod
PKCE challenge method to use with the Authorization Code flow.
OAuth2PkceMethod.S256 ("S256") — SHA-256 challenge (recommended)OAuth2PkceMethod.Plain ("plain") — plain challenge See PKCE support . Client Credentials fields Required when oauth2Type is OAuth2Type.ClientCredentials:
definition.inputs.tokenUrl
The OAuth 2.0 token URL for exchanging client credentials for an access token.
OAuth 2.0 permissions to request.
definition.inputs.clientId
The OAuth 2.0 client ID.
definition.inputs.clientSecret
The OAuth 2.0 client secret.
The templateConnectionInputs function merges explicitly provided connection inputs with template inputs for the missing required OAuth 2.0 fields. This lets you provide custom labels or defaults for some fields while using sensible defaults for others.
import { templateConnectionInputs , OAuth2Type } from "@prismatic-io/spectral" ; const inputs = templateConnectionInputs ( { // Custom values for fields you want to control clientId: { label: "App Key" , type: "string" , required: true , placeholder: "Your app key" , }, clientSecret: { label: "App Secret" , type: "password" , required: true , placeholder: "Your app secret" , }, }, { // Template inputs fill in missing required fields authorizeUrl: { type: "template" , templateValue: "https://app.acme.com/oauth2/authorize" , shown: false }, tokenUrl: { type: "template" , templateValue: "https://app.acme.com/oauth2/token" , shown: false }, scopes: { type: "template" , templateValue: "read write" , shown: false }, }, OAuth2Type . AuthorizationCode , );
Examples Authorization Code
Client Credentials
import { oauth2Connection , OAuth2Type , OAuth2PkceMethod , component , } from "@prismatic-io/spectral" ; export const acmeOAuth2 = oauth2Connection ({ key: "acmeOAuth2" , display: { label: "Acme OAuth 2.0" , description: "Connect to Acme using OAuth 2.0 Authorization Code flow" , icons: { avatarPath: "acme-logo.png" , oauth2ConnectionIconPath: "acme-connect-button.png" , }, }, oauth2Type: OAuth2Type . AuthorizationCode , oauth2PkceMethod: OAuth2PkceMethod . S256 , oauth2Config: { oAuthSuccessRedirectUri: "https://app.acme.com/oauth/success" , oAuthFailureRedirectUri: "https://app.acme.com/oauth/failure" , }, inputs: { authorizeUrl: { label: "Authorization URL" , type: "string" , required: true , default: "https://app.acme.com/oauth2/authorize" , shown: false , }, tokenUrl: { label: "Token URL" , type: "string" , required: true , default: "https://app.acme.com/oauth2/token" , shown: false , }, scopes: { label: "Scopes" , type: "string" , required: true , default: "read write" , shown: false , }, clientId: { label: "Client ID" , type: "string" , required: true , placeholder: "Your OAuth 2.0 client ID" , }, clientSecret: { label: "Client Secret" , type: "password" , required: true , writeOnly: true , placeholder: "Your OAuth 2.0 client secret" , }, }, }); export default component ({ key: "acmeComponent" , display: { label: "Acme" , description: "Connect to Acme" , iconPath: "icon.png" , } , connections: [ acmeOAuth2 ] , }) ;
import { oauth2Connection , OAuth2Type , component , } from "@prismatic-io/spectral" ; export const acmeClientCreds = oauth2Connection ({ key: "acmeClientCredentials" , display: { label: "Acme API (Machine-to-Machine)" , description: "Connect to Acme using OAuth 2.0 Client Credentials" , }, oauth2Type: OAuth2Type . ClientCredentials , inputs: { tokenUrl: { label: "Token URL" , type: "string" , required: true , default: "https://api.acme.com/oauth2/token" , shown: false , }, scopes: { label: "Scopes" , type: "string" , required: true , default: "api:read api:write" , shown: false , }, clientId: { label: "Client ID" , type: "string" , required: true , placeholder: "Your client ID" , }, clientSecret: { label: "Client Secret" , type: "password" , required: true , writeOnly: true , placeholder: "Your client secret" , }, }, });
Using an OAuth 2.0 connection in an action import { action , input } from "@prismatic-io/spectral" ; export const listContacts = action ({ display: { label: "List Contacts" , description: "Retrieve contacts" }, inputs: { connection: input ({ label: "Connection" , type: "connection" , required: true }), }, perform : async ( context , params ) => { const { token } = params . connection ; const accessToken = token ?. access_token as string ; const response = await fetch ( "https://api.acme.com/contacts" , { headers: { Authorization: `Bearer ${ accessToken } ` }, }); return { data: await response . json () }; }, });
Prismatic automatically refreshes OAuth 2.0 access tokens before they expire. You do not need to implement token refresh logic in your component.
