# uip is connectors builder auth

> Syntax and options for configuring and inspecting a connector's authentication scheme with the Integration Service connector builder — auth set, auth get, and auth system create/list.

This page covers `uip is connectors builder auth`, the command group that defines a connector's own authentication scheme — how the connector itself talks to its vendor API. This is a design-time concern, distinct from a tenant [connection](./uip-is-connections.md), which is a runtime instance of that scheme (a specific user's credentials against the scheme this page configures). For connector directory resolution, the design-vs-published distinction, and the overall authoring flow, see [Concepts](./uip-is-connectors-builder.md#concepts) on the parent page.

## Synopsis

```text
uip is connectors builder auth set --auth-type <type> [scheme-specific options] [--connector-dir <path>]
uip is connectors builder auth get [--connector-dir <path>]
uip is connectors builder auth system create --type <type> [--vendor-path <path>] [--method <method>] [--next-resource <selector>] [--path <path>] [--connector-dir <path>]
uip is connectors builder auth system list [--connector-dir <path>]
```

None of these options are tenant-scoped — there is no `--tenant` flag anywhere in this group. Everything here edits or reads the local connector directory only.

## uip is connectors builder auth set

Configure authentication on the connector. One `--auth-type` is required; which of the remaining options apply depends on that type. Re-running against an already-configured connector fails unless `--force` is passed, which applies the diff to existing config entries instead of erroring — this exists because a first attempt can be rejected (for example, a scope-options change that conflicts with existing config) and needs to be retried.

:::note
Use this to wire authentication on an existing connector, for any of the auth types below, or to swap an existing connector's auth type (`--force`). Define OAuth/JWT scopes here too, via `--scope-options`/`--required-scopes`/`--preselected-scopes` — there is no separate `auth scope` command. Do not use this to create a connector from scratch — use [`builder init`](./uip-is-connectors-builder-init.md) first. Do not use this for non-auth configuration entries — use `builder init preset apply` or `builder state patch` (see [Trigger & state](./uip-is-connectors-builder-trigger.md)).
:::

### Options

| Long | Value | Applies to | Description |
|---|---|---|---|
| `--auth-type <type>` | one of the types below | all | **Required.** The auth flow to configure. |
| `--connector-dir <path>` | path | all | Connector directory. Same resolution order as [Concepts](./uip-is-connectors-builder.md#concepts). |
| `--force` | flag | all | Apply diffs to existing config entries instead of erroring when the connector is already configured. |
| `--authorization-url <url>` | url | OAuth | Login/consent URL. |
| `--token-url <url>` | url | OAuth, JWT | Token endpoint. |
| `--token-refresh-url <url>` | url | OAuth | Defaults to `--token-url`. |
| `--token-revoke-url <url>` | url | OAuth | Token revoke endpoint. |
| `--scope <scope>` | string | OAuth, JWT, `firstPartyService` | Space-delimited scope string. For `firstPartyService`, the platform scope the minted token carries. |
| `--jwt-claim <spec>` | `name[=value][;label=...][;hint=...]`, repeatable | `jwtOauth`, `jwtOauth2` | JWT assertion claim. A bare name (no `=value`) is created required-and-empty so the connection user fills it at connect time; `label`/`hint` set the connection-form display name and hint text. |
| `--jwt-header <spec>` | same syntax as `--jwt-claim`, repeatable | `jwtOauth`, `jwtOauth2` | JWT assertion header. |
| `--aws-service-name <name>` | string | `awsv4` | SigV4 service name constant (for example `polly`, `connect`); sets the hidden `aws.service.name` default. |
| `--scope-options <json>` | JSON array of `{description, value}` | OAuth, JWT | Multiselect scope choices offered to the connection user. |
| `--scope-options-file <path>` | path | OAuth, JWT | Read `--scope-options` JSON from a file instead of inline. |
| `--required-scopes <csv>` | comma-separated | OAuth, JWT | Scopes the user cannot deselect. |
| `--preselected-scopes <csv>` | comma-separated | OAuth, JWT | Scopes pre-checked by default. |
| `--scope-delimiter <char>` | string | OAuth, JWT | Scope separator. Default: space. |
| `--scope-hint-text <text>` | string | OAuth, JWT | Hint text shown under the scope selector. |
| `--scope-screen-type <type>` | string | OAuth, JWT | `configScreenType` for the scope entry. Default: `pre`. |
| `--api-key-param-name <name>` | string | `customApiKey` | Required vendor header or query parameter name. |
| `--api-key-location <where>` | `header` \| `query` | `customApiKey` | Where the key is sent. Default: `header`. |
| `--api-key-prefix <prefix>` | string | `customApiKey` | Literal prefix prepended to the key value. |
| `--key-config-name <key>` | string | `customApiKey` | Internal config key. Default: `custom.api.key`. |
| `--key-config-display-name <name>` | string | `customApiKey` | UI label. Default: `API Key`. |
| `--validation-vendor-path <path>` | path | all (optional) | Add a `provisionAuthValidation` test call at this vendor path. |
| `--validation-method <method>` | HTTP method | all (optional) | Method for the auth-validation call. Default and recommended: `GET` — the probe must be read-only and must not change vendor data. |
| `--auth-header <kv>` | `ConfigName=VendorHeader`, repeatable | multi-header schemes | Extra static auth header, created as a plain text config the connection user fills in. For schemes needing more than one credential header (for example iContact's `API-AppId`/`API-Username`). |
| `--secret-auth-header <kv>` | `ConfigName=VendorHeader`, repeatable | multi-header schemes | Like `--auth-header`, but the config is created as an encrypted password field. For credential headers such as `API-Password`. |

`--auth-type` accepts one of: `oauth2`, `oauth2Pkce`, `oauth2ClientCredentials`, `oauth2Password`, `oauth2PrivateKeyJwt`, `oauth1`, `basic`, `jwtOauth`, `jwtOauth2`, `custom`, `customApiKey`, `personalAccessToken`, `awsv4`, `googleServiceAccount`, `rsaCertificate`, `none`, `firstPartyService`, `fpsUserDelegatedAccess`, `fpsRobotAccess`.

`firstPartyService` is UiPath platform-injected identity: the platform mints and refreshes the token, binding `{host}`/`{account}`/`{tenant}` to platform headers instead of connection-time config fields (those three fields are actually **removed** from the config set when you switch to this type, as shown in the example below).

Each auth type writes a different config bundle — the examples below each show a real, type-specific result rather than one generic shape.

### Examples

```bash
# OAuth2 authorization-code flow
uip is connectors builder auth set --auth-type oauth2 \
  --authorization-url https://acme.com/oauth/authorize \
  --token-url https://acme.com/oauth/token \
  --scope 'read write'
```

```json
{
  "Code": "AuthConfigured",
  "Data": {
    "AuthType": "oauth2",
    "AuthenticationTypes": ["oauth2"],
    "TypeOauth": true,
    "OauthRefreshResourceCreated": true,
    "ConfigChanges": {
      "added": ["oauth.api.key", "oauth.api.secret", "oauth.token.url"],
      "updated": [],
      "unchanged": []
    }
  }
}
```

```bash
# customApiKey, sent as a header
uip is connectors builder auth set --auth-type customApiKey --api-key-param-name X-API-Key
```

```json
{
  "Code": "AuthConfigured",
  "Data": {
    "AuthType": "customApiKey",
    "AuthenticationTypes": ["customApiKey"],
    "TypeOauth": false,
    "ApiKeyConfigAdded": true,
    "ApiKeyParamAdded": true,
    "KeyConfigName": "custom.api.key",
    "ConfigChanges": { "added": ["custom.api.key"], "updated": [], "unchanged": [] }
  }
}
```

```bash
# Re-apply a config diff that was rejected on first try
uip is connectors builder auth set --auth-type customApiKey --api-key-param-name X-API-Key --force
```

```json
{
  "Code": "AuthConfigured",
  "Data": {
    "AuthType": "customApiKey",
    "ConfigChanges": {
      "added": [],
      "updated": [{ "key": "custom.api.key", "diff": { "displayOrder": [3, 1] } }],
      "unchanged": []
    }
  }
}
```

```bash
# OAuth 2.0 JWT Bearer (Salesforce-style): claims with a value are pre-filled,
# bare claims are filled in by the connection user
uip is connectors builder auth set --auth-type jwtOauth \
  --token-url https://login.salesforce.com/services/oauth2/token \
  --jwt-claim aud=https://login.salesforce.com \
  --jwt-claim iss \
  --jwt-claim sub
```

```json
{
  "Code": "AuthConfigured",
  "Data": {
    "AuthType": "jwtOauth",
    "AuthenticationTypes": ["jwtOauth"],
    "TypeOauth": true,
    "ConfigChanges": {
      "added": [
        "oauth.api.key", "oauth.api.secret", "oauth.callback.url", "oauth.token.url",
        "jwt.base64.encoded.key", "jwt.claim.aud", "jwt.claim.iss", "jwt.claim.sub"
      ],
      "updated": [],
      "unchanged": []
    }
  }
}
```

```bash
# UiPath first-party service auth (platform-injected identity)
uip is connectors builder auth set --auth-type firstPartyService --scope OrchestratorApiUserAccess
```

```json
{
  "Code": "AuthConfigured",
  "Data": {
    "AuthType": "firstPartyService",
    "AuthenticationTypes": ["firstPartyService"],
    "TypeOauth": false,
    "ConfigChanges": {
      "added": [
        "oauth.scope", "oauth.basic.header", "oauth.user.token",
        "oauth.user.refresh_time", "oauth.user.refresh_interval"
      ],
      "updated": [],
      "unchanged": [],
      "removed": ["host", "account", "tenant"]
    }
  }
}
```

```bash
# No authentication
uip is connectors builder auth set --auth-type none
```

```json
{
  "Code": "AuthConfigured",
  "Data": {
    "AuthType": "none",
    "AuthenticationTypes": ["none"],
    "TypeOauth": false,
    "ConfigChanges": { "added": [], "updated": [], "unchanged": [] }
  }
}
```

## uip is connectors builder auth get

Read the connector's full authentication setup: type, config entries (secrets redacted), lifecycle resources, and FPS header bindings.

:::note
Use this to inspect the connector's current authentication block. To change it, use `auth set`.
:::

### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Connector directory. Same resolution order as [Concepts](./uip-is-connectors-builder.md#concepts). |

### Example

```bash
uip is connectors builder auth get
```

### Data shape (--output json)

```json
{
  "Code": "AuthInfo",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "Authentication": {
      "Type": "jwtOauth",
      "AuthenticationTypes": ["jwtOauth"],
      "TypeOauth": true
    },
    "Configs": [
      {
        "key": "oauth.token.url",
        "configScreenType": null,
        "required": true,
        "hidden": true,
        "defaultValue": "https://login.acme.com/oauth2/token"
      },
      {
        "key": "jwt.claim.iss",
        "configScreenType": "pre",
        "required": true,
        "defaultValue": null
      }
    ],
    "ConnectionFormFields": [],
    "Resources": {
      "oauthOnTokenRefresh": false,
      "provisionAuthValidation": true
    },
    "FpsBindings": null,
    "TemplateBindings": null
  }
}
```

Secret-typed config values (passwords, API keys) are never included — only the config's metadata (key, whether it's required/hidden, non-secret default).

## uip is connectors builder auth system

Manage connector-lifecycle ("system") resources — auth-time hooks such as `provisionAuthValidation`, `onProvision`, and `oauthOnTokenRefresh`. These live under `auth` because they're auth-lifecycle hooks: element.json entries with no separate SR (Semantic Resource) file, unlike a normal API endpoint created by `activity create` (or an ad-hoc SR-less endpoint via `activity create --skip-sr` — see [Activity & hooks](./uip-is-connectors-builder-activity.md)).

### uip is connectors builder auth system create

:::note
Use this to wire a lifecycle hook endpoint — auth-validation, onProvision, or a token-refresh call. Do not use this to add a normal API endpoint — use `builder activity create` instead.
:::

#### Options

| Long | Value | Description |
|---|---|---|
| `--type <type>` | string | **Required.** System resource type, for example `provisionAuthValidation`, `onProvision`, `oauthOnTokenRefresh`. |
| `--vendor-path <path>` | path | Vendor API path for this hook. |
| `--method <method>` | HTTP method | Defaults to `POST` when the type requires a method. |
| `--next-resource <selector>` | `METHOD:/path` | Chain to a next resource, for example `GET:/organization`. |
| `--path <path>` | path | Explicit resource path — must match the type's override path when that type declares one. |
| `--connector-dir <path>` | path | Connector directory. Same resolution order as [Concepts](./uip-is-connectors-builder.md#concepts). |

#### Example

```bash
uip is connectors builder auth system create --type provisionAuthValidation --vendor-path /me
```

#### Data shape (--output json)

```json
{
  "Code": "SystemResourceCreated",
  "Data": {
    "ResourceName": "provisionAuthValidation",
    "ConnectorRoot": "/work/my-acme-connector",
    "ResourceType": "provisionAuthValidation",
    "ElementEntriesAdded": ["provisionAuthValidation"],
    "ElementEntriesSkipped": [],
    "SkipSr": true
  }
}
```

### uip is connectors builder auth system list

Lists the connector's element.json entries whose type is a system resource.

#### Options

| Long | Value | Description |
|---|---|---|
| `--connector-dir <path>` | path | Connector directory. Same resolution order as [Concepts](./uip-is-connectors-builder.md#concepts). |

#### Example

```bash
uip is connectors builder auth system list
```

#### Data shape (--output json)

```json
{
  "Code": "SystemResourceList",
  "Data": {
    "Resources": [
      { "name": "provisionAuthValidation", "type": "provisionAuthValidation" }
    ]
  }
}
```

## Related

- [Overview & tenant lifecycle](./uip-is-connectors-builder.md) — concepts shared across all builder pages, plus `download`/`import`/`publish`/`publish-status`.
- [Init & connector](./uip-is-connectors-builder-init.md) — scaffold a connector before configuring its auth.
- [Activity & hooks](./uip-is-connectors-builder-activity.md) — define the endpoints that use this auth once it's configured.
- [Trigger & state](./uip-is-connectors-builder-trigger.md) — event triggers and low-level element-file edits.
- [`uip is connections`](./uip-is-connections.md) — the tenant-side runtime instance of the scheme configured here.

## See also

- [Integration Service tool overview](./uip-is.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)