Services and credentials
Services hold credentials and settings for external systems, such as API keys, OAuth2 accounts, and certificates. Your application declares which services it needs. People enter the values in Adapt, and your code uses them through the SDK. Credentials never appear in your code, settings, pages, or logs.
Use services for credentials, and for settings that people reuse across vertices and projects. Use vertex settings for everything that belongs to one vertex instance.
Service types
Section titled “Service types”| Type | Use it for | Your code gets |
|---|---|---|
httpProxy |
An HTTP API that needs secret headers or a client certificate. | A fetch function. Adapt adds the secrets, so your code never sees them. |
variable |
A value that your code must read, such as an account number. | The value. |
oauth2 |
OAuth2 accounts. | Access tokens. Adapt refreshes them. |
group |
Services that belong together. | Each member. |
oneof |
A choice, such as Google or Microsoft calendars. | The chosen option. |
Declare and attach
Section titled “Declare and attach”Define each service in serviceDefinitions in manifest.json. Then attach it by name:
- In
userServicesinvertex.json, when each user brings their own credentials. Read them withuserHttpProxy,getUserVariable, andgetUserToken. - In
systemServicesinmanifest.json, when you configure them once for all users. Read them withsystemHttpProxy,getSystemVariable, andgetSystemToken.
Example: an API key
Section titled “Example: an API key”{ "serviceDefinitions": [ { "name": "remoteApi", "label": "Remote API", "description": "Your API key for Example API.", "httpProxy": { "allowedHosts": ["api.example.com:443"], "injectHeaders": { "Authorization": { "template": "Bearer %API_KEY%" } } } } ]}{ "userServices": ["remoteApi"]}Users enter API_KEY in the service’s settings in Adapt. Your code calls the API through the proxy:
const request = api.userHttpProxy("remoteApi");const response = await request("https://api.example.com/items");If a library accepts a custom fetch function, give it the proxy’s function. For client certificates, set "tls": { "mode": "MODE_MTLS" } in the proxy.
Variables
Section titled “Variables”A variable has a JTD schema. Variables are secret by default. Set plaintext: true only for values that are not secret, such as a public style:
{ "name": "brand_color", "label": "Brand color", "optional": true, "variable": { "schema": { "type": "string", "metadata": { "format": "ECMAScript regular expression: ^#[0-9a-fA-F]{6}$" } }, "plaintext": true }}const color = await api.getUserVariable<string>("brand_color");Restrictions in the schema’s metadata, such as this pattern, are only hints. Validate the value in your code.
OAuth2
Section titled “OAuth2”For the authorization code grant, define the service once, and attach it twice:
- in
systemServices, where you configure your OAuth client and its secret, - in each vertex’s
userServices, where users connect their own accounts.
{ "serviceDefinitions": [ { "name": "crm", "label": "Example CRM account", "description": "Reads and creates contacts in your Example CRM account.", "oauth2": { "grantType": "OAUTH2_GRANT_TYPE_AUTHORIZATION_CODE", "scopes": ["openid", "contacts.read", "contacts.write"], "authMethod": "OAUTH2_AUTH_TYPE_FORM", "clientId": "REPLACE_WITH_CLIENT_ID", "tokenEndpoint": "https://auth.example.com/oauth2/token", "code": { "authEndpoint": "https://auth.example.com/oauth2/authorize", "usePkce": true } } } ], "systemServices": ["crm"]}const { token } = await api.getUserToken("crm");- Ask for scopes and parameters that make the provider return a refresh token. Google, for example, needs
access_type=offlineandprompt=consentincode.additionalParams. - Register the callback URL that Adapt shows in your application’s system service settings with the provider. For the emulator, see OAuth2 in the emulator.
Groups and choices
Section titled “Groups and choices”Define every member of a group or option of a oneof in serviceDefinitions, and attach only the outer service. In code, reach a service by its path of names, joined with dots:
// "storage" is a oneof. Its option "gcs" is a group with "gcs_oauth" and "bucket".const { token } = await api.getUserToken("storage.gcs.gcs_oauth");const bucket = await api.getUserVariable<string>("storage.gcs.bucket");Optional services
Section titled “Optional services”An optional service can be missing, and a user picks only one option of a oneof. Check before you use them:
const { configuredServices } = await api.getConfig("configuredServices");if (configuredServices["storage.gcs.gcs_oauth"]) { // Use Google Cloud Storage.}For system services, use api.getSystemServices().
Credentials in the browser
Section titled “Credentials in the browser”Keep tokens and credentials in the runtime. Send one to a browser only when the provider documents that flow for browsers, and the credential is limited to what that user may do. If a secret is needed to create it, create it in the runtime, and send only the result.
Change services later
Section titled “Change services later”Changes to service definitions can reset the settings of people who already use your application. See Service changes before you release one.