Authorization Credentials
Credentials are deprecated
Credentials are being phased out in favor of connections. You can read about this change on our blog.
#
OverviewMany services that Prismatic components connect to require credentials. SFTP servers might require basic auth username/password or an SSH key, services like Dropbox require OAuth2 tokens, and HTTP endpoints often require an API key. Credentials and keys are not something you want to store in plain text.
Prismatic provides a credential manager for storing sensitive credentials for each instance. They are stored encrypted at rest with a unique encryption key per tenant, and are encrypted in transit when transferred over a network.
For a quickstart on using credentials in an integration, click here.
#
Authorization MethodsPrismatic components can use a variety of authorization methods (credential types) to interact with external services.
#
API Key / SecretAPI Key / Secret is used by components to access services that require a key/secret pair.
For example, AWS Authorization requires an access_key_id
and secret_access_key
, which can be placed in the api_key
and api_secret
fields respectively.
Key: api_key_secret
Fields: api_key
and api_secret
.
#
Basic AuthBasic Auth is generally used for HTTP or FTP(S) transactions. A username and password are presented in the form of an HTTP header, which an endpoint accepts or rejects.
Key: basic
Fields: username
and password
.
#
Private Key AuthorizationSome components, like SFTP, may use public/private key pairs to perform authorization. A username and the private key portion of the key pair can be stored in Prismatic's credential store.
Key: private_key
Fields: username
and private_key
.
#
API Key AuthorizationAn API key is a single token (often a JWT token or similar) that contains signed user information and can be exchanged for authorization to a resource.
Key: api_key
Fields: api_key
#
OAuth 2.0 AuthorizationMany outside software providers use OAuth 2.0 to grant access to resources. Prismatic currently supports two types of OAuth 2.0 flows:
#
OAuth 2.0 - Authorization Code FlowThe OAuth 2.0 "Authorization Code Flow" is the most common type of OAuth flow, and is appealing because you don't need to handle customers' credentials (so customers won't be motivated to send their credentials to you in an insecure manner). Instead, you configure client ID, client secret, authorization scopes, and authorization and access token URLs, and your customers then enter their credentials separately.
Prismatic then receives an "authorization code" that is then exchanged for an access token, and usually a refresh token as well. If the access token has an expiration date, Prismatic will use the refresh token to fetch a new access token prior to expiration. Prismatic can then access the customer's system on behalf of the customer, without needing to know the customer's credentials.
Key: oauth2
Fields: client_id
, client_secret
, scopes
, auth_uri
, and token_uri
For More Information: The OAuth 2.0 flow, Auth0's Explanation of the Authorization Code Flow
#
OAuth 2.0 - Client Credentials FlowWith the OAuth 2.0 "Client Credentials Flow", a client ID and secret are passed to an authorization provider, and an access token is passed back to the requester. This differs from the "Authorization Code Flow" since customers do not enter credentials themselves.
Key: oauth2_client_credentials
Fields: client_id
, client_secret
, scopes
, and token_uri
For More Information: Auth0's Explanation of the Client Credentials Flow
#
Should I Create Organization or Customer Credentials?You should create credentials at the organization level if multiple customers will need access to those credentials. For example, if there is a shared API key that all of your customers will use to access a resource, you will want to create a credential at the organization level.
If credentials are customer-specific, you will want to create the credential at the customer level. For example, you might have AWS accounts for each of your customers. You would create an AWS credential for each customer at the customer level to handle AWS-related actions.
#
Creating New CredentialsCredentials can be organization-wide or customer-specific.
To create new credentials you will need to know whether you want the credentials to be stored at the organization or customer level, what type of credentials you wish to store (reference the authorization method key
above), as well as the credentials themselves.
- Web App
- CLI
- API
To create credentials at the organization level, click the Settings link on the left-hand sidebar, and then select the Credentials tab.
To create credentials at the customer level, click Customers on the left-hand sidebar, choose a customer, and select the Credentials tab.
Click the + Credential button on the top-right side of either screen.

After entering a name for your credentials and selecting an authorization method, you will be prompted to enter your credentials. Input fields on this page will change based on what authorization method you chose.
After entering your credentials, be sure to click Save to save your changes.

To create credentials for an organization or customer, you will need to know the ID of the authorization method you wish to use.
AUTH_TYPE_ID=$(prism authorization-methods:list --output json --extended | jq -r '.[] | select(.key == "api_key").id')
prism organization:credentials:create \ --label 'JWT to website.com' \ --authorization-method ${AUTH_TYPE_ID} \ --fields '{"api_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiUHJpc21hdGljIiwiaXNCZXN0Ijp0cnVlfQ.vZVPo0uF4OBlZWKTuXipCDS4tsfq74aQTs3wRROqM_M"}'
CUSTOMER_ID=$(prism customers:list --columns=id --filter 'name=MY CUSTOMERS NAME' --no-header)
AUTH_TYPE_ID=$(prism authorization-methods:list --output json --extended | jq -r '.[] | select(.key == "basic").id')
prism customers:credentials:create \ --label 'User/pass for website.com/resource' \ --authorization-method ${AUTH_TYPE_ID} \ --customer ${CUSTOMER_ID} \ --fields '{"username": "myuser", "password": "MyP@$sW0Rd!"}'
To create a new set of credentials for your organization or for a customer, first find the ID of the authentication method (basic
, api_key
, etc), that you want to add:
query { authorizationMethods { nodes { id key label } }}
Then, use the ID to create a new customer credential using the createCustomerCredential mutation:
mutation( $customer: ID! $label: String! $authorizationMethod: ID! $values: [InputCredentialFieldValue]) { createCustomerCredential( input: { customer: $customer label: $label authorizationMethod: $authorizationMethod values: $values } ) { credential { id } }}
{ "customer": "Q3VzdG9tZXI6MmM4YmUxZDgtOTU5Ny00MTI3LWI5MTUtYjBmMjc3Y2YyNWYw", "label": "User/pass for website.com/resource", "authorizationMethod": "QXV0aG9yaXphdGlvbk1ldGhvZDo0OWUwMTUzYS00OGM0LTQxYzktYWY1YS1kNzIxODhkN2UyNDU=", "values": [ { "key": "username", "value": "myuser" }, { "key": "password", "value": "MyP@$sW0Rd!" } ]}
The same can be done for organization credentials using the createOrganizationCredential mutation.
#
Listing Credentials- Web App
- CLI
- API
To view credentials for the organization, click the Settings link on the left-hand sidebar, and then select the Credentials tab.
To view credentials for a specific customer, click Customers on the left-hand sidebar, choose a customer, and select the Credentials tab.
To view all credentials for all customers, click the Credentials link on the left-hand sidebar.
From any of these credentials pages, you can filter credentials by label using the search bar on the top of the page.
Credentials with incomplete setup (missing fields; incomplete OAuth 2.0 flow, etc) will be marked with a red bar on the left-hand side.

Credentials can be listed with the organization:credentials:list
and customers:credentials:list
subcommands respectively.
prism organization:credentials:list
Label Authorization Method Ready for Use ───────────────────────────── ──────────────────── ───────────── TIE S3 Bucket Auth API Key / Secret true Pokemon S3 Bucket Credentials API Key / Secret true Rocket 3D Printer Basic Auth Basic Auth true
CUSTOMER_ID=$(prism customers:list --columns=id --filter 'name=Smith Rocket Company' --no-header)
prism customers:credentials:list --customer ${CUSTOMER_ID}
Label Authorization Method Ready for Use ────────────────────────────────── ──────────────────── ───────────── SFTP Credentials Basic Auth true User/pass for website.com/resource Basic Auth true
Query organization for associated credentials:
query { organization { credentials { nodes { id authorizationMethod { key } values { key value } } } }}
Or query customer for customer credentials:
query { customer(id: "Q3VzdG9tZXI6MmM4YmUxZDgtOTU5Ny00MTI3LWI5MTUtYjBmMjc3Y2YyNWYw") { credentials { nodes { id authorizationMethod { key } values { key value } } } }}
#
Updating Credentials- Web App
- CLI
- API
prism organization:credentials:update \ EXAMPLEudGlhbDpkMDUzMGZhNi1jYjZmLTRkZWUtOWQ4OC00MDA0Y2M3MzZhMWQ= \ --fields '{"username": "myUsername", "password": "myPassword"}' \ --label 'myExampleLabel'
prism customers:credentials:update \ EXAMPLEudGlhbDplYzExNjE4Mi1hM2RlLTQwMzMtYTJhYi0wMmE1OGIxODE3Njg= \ --fields '{"username": "myUsername", "password": "myPassword"}' \ --label 'myExampleLabel'
query { organization { credentials { nodes { id name } } }}
Note that if you are trying to grab a customer credential, you must alter your query like the following:
query { customer { credentials { nodes { id name } } }}
Once you have the Id of the credential, you can use it to execute this graphql mutation.
mutation updateCustomerCredential( $label: String $values: [InputCredentialFieldValue] $id: ID) { updateCredential(input: { label: $label, values: $values, id: $id }) { errors { field messages } credential { id org { id name } customer { id name } } }}
{ "label": "exampleLabel", "values": [ { "key": "api_key", "value": "ExampleAPIKey" }, { "key": "api_secret", "value": "ExampleAPISecret" } ], "id": "Q3JlZGVudGlhbDo1Yjg0YjAyMC1mNzQ2LTQ3MTktODI0ZS0zNWU3ZWM2NTM1YWI="}
#
Deleting Credentials- Web App
- CLI
- API
From any credential list page, click a credential. Select the credential's Summary tab and click Delete Credential. Type the name of the credential and click REMOVE CREDENTIAL to confirm deletion.

To delete a credential, you will need to find the credential's ID, and then use the organization:credentials:delete
or customers:credentials:delete
subcommands.
prism organization:credentials:list --extended
Id Label Authorization Method Ready for Use ──────────────────────────────────────────────────────────────── ───────────────────────────── ──────────────────── ───────────── Q3JlZGVudGlhbDo0YTIxMDdiNS0wZWNmLTQ3YWMtOTcyOS0zOGEzMjFiNjIzOGE= TIE S3 Bucket Auth API Key / Secret true Q3JlZGVudGlhbDo0ZDkxYmRlZC1kYWNkLTRlNzctYjEzNi02ZDNiYzNhNjNkZmE= Pokemon S3 Bucket Credentials API Key / Secret true Q3JlZGVudGlhbDo2OWRmNzdmNC01NmQ1LTQ2Y2MtYWIwOS1iNTQ5NzhiZmE5ZjE= Rocket 3D Printer Basic Auth Basic Auth true
prism organization:credentials:delete Q3JlZGVudGlhbDo2OWRmNzdmNC01NmQ1LTQ2Y2MtYWIwOS1iNTQ5NzhiZmE5ZjE=
To delete a customer or organization credential, use the deleteCredential mutation:
mutation { deleteCredential( input: { id: "Q3JlZGVudGlhbDo3NDgyOTA4Yi0wNDNkLTRlYjQtYTA1YS0xNzJkMzI2ZGQ0NDA=" } ) { credential { id } }}
#
Testing CredentialsCredentials can be tested using the integration designer.
For More Information: Testing Credentials in Integrations
#
The OAuth 2.0 FlowOAuth 2.0 is complex. Writing an OAuth client outside of Prismatic involves managing a callback URL that you host, exchanging authentication codes for authentication tokens that expire, juggling token renewals, etc. Prismatic takes care of these complexities for you. This section describes generally how to set up OAuth 2.0 credentials for a customer, and the next section gives a specific example using Dropbox's OAuth 2.0 flow.
First, you will need to create an "app" with your desired OAuth provider (Facebook, Twitter, Google, Dropbox, etc., are all similar in this respect). Your OAuth provider will generate a client ID and client secret, though some providers call these different things (like "app key" and "app secret"). You will need to make note of this client ID and secret.
Next, you will need to add https://oauth2.prismatic.io/callback to the list of of allowed redirect URIs for your OAuth app. This will permit the OAuth provider to send authorization codes to Prismatic's callback URL when users authenticate.
Then, after your OAuth "app" is configured you will need to create new OAuth 2.0 credentials in the Prismatic web app for each of your customers who need credentials using the client ID and secret you noted above. Your OAuth provider will provide you with authorization and token URLs and permission scopes - enter these into the Prismatic web app, as well. These URLs and permission scopes can likely be found in the OAuth provider's developer documentation, probably under a section having to do with authentication and authorization.
It's uncommon, but some OAuth 2.0 applications require custom HTTP headers. To add custom headers to the authorization and token HTTP requests, click the + Header button on the bottom of the OAuth credential configuration screen:

After configuring a credential in the Prismatic web app, either you or your customer will need to authenticate against the OAuth provider. You can authenticate yourself by following a link that the Prismatic web app generates, or you can have your customer enter their credentials by emailing a link to your customer through the Prismatic web app. Since the purpose of OAuth is to avoid unsafe sharing of credentials, we recommend that you have your customers authenticate by emailing them a link.
After you or your customer authenticates against the OAuth provider, the provider will send an authorization code to Prismatic's callback URL, and Prismatic will take care of the rest - exchanging the authorization code for an access token, refreshing the access token periodically before it expires, and passing the access token into components that need it.
A note about refreshing tokens
Some OAuth providers have access tokens that expire. Others don't. If your OAuth provider expires access tokens, it is important that Prismatic is also provided a refresh token. The refresh token will allow Prismatic to request a new access token automatically prior to expiration.
This refresh flow is often referred to as "offline access."
Some OAuth providers grant "offline access" via a scope (usually called offline
), and others provide an auth URL parameter, like ?token_access_type=offline
.
Check your OAuth provider's documentation for how to either generate an access token that doesn't expire, or how to generate a refresh token.
#
Dropbox OAuth 2.0 Flow ExampleLet's look at how to set up an OAuth 2.0 credential with Dropbox.
First, log on to https://www.dropbox.com/developers/apps and select Create app. Select a Scoped access API and choose App folder for the type of access you need. Name your app whatever you'd like.

Click Create App. Under the next Settings tab, take note of your App key and App secret, and add https://oauth2.prismatic.io/callback to the list of Redirect URIs.

Finally, under the Permissions tab check the files.content.write and files.content.read scopes so your integration can read and write files within Dropbox on behalf of your customer.

Switch to the Prismatic web app and open an instance for which you want to create some credentials. Click the + Credential button. Give your credential a name and choose OAuth 2.0 - Authorization Code for the authorization method.

Within the Credentials tab, enter the Dropbox App key and App secret you noted before as your Client ID and Client Secret. Leave Scopes blank, and under Authorization URL and Access Token URL enter https://www.dropbox.com/oauth2/authorize?token_access_type=offline and https://api.dropboxapi.com/oauth2/token respectively. These URLs were found in Dropbox's developer documentation.

At this point, our OAuth 2.0 flow is set up. We now need to have someone, either a customer or organization team member, enter their OAuth credentials to authorize Prismatic to interact with Dropbox on their behalf. We recommend emailing customers a URL and having them authenticate, so they're not tempted to email credentials to you. Do this by clicking the OAuth2 Authorization tab, enter a customer's email address, and then click Send email to send an authorization URL to your customer.

Once a user authenticates against Dropbox and and Dropbox sends Prismatic an authorization code, you will see Customer authorization complete on the top of this screen.

After the authentication process is complete, the credential can be used in an integration. In this screenshot you can see our credential being used to successfully list files contained in a Dropbox folder:
