Skip to content

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.

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.

Define each service in serviceDefinitions in manifest.json. Then attach it by name:

  • In userServices in vertex.json, when each user brings their own credentials. Read them with userHttpProxy, getUserVariable, and getUserToken.
  • In systemServices in manifest.json, when you configure them once for all users. Read them with systemHttpProxy, getSystemVariable, and getSystemToken.
manifest.json (excerpt)
{
"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%" }
}
}
}
]
}
src/ticket_form/vertex.json (excerpt)
{
"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.

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:

manifest.json (excerpt)
{
"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.

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.
manifest.json (excerpt)
{
"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=offline and prompt=consent in code.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.

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");

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().

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.

Changes to service definitions can reset the settings of people who already use your application. See Service changes before you release one.