---
title: OIDC connectors | Runware Docs
url: https://runware.ai/docs/serverless/api-oidc-connectors
description: Manage your organization's OIDC connectors and attach them to the apps whose workers authenticate with them.
relatedDocuments:
  - https://runware.ai/docs/serverless/api
  - https://runware.ai/docs/serverless/oidc-connectors
  - https://runware.ai/docs/serverless/api-secrets
---
## Introduction

An OIDC connector is **where an app's workers send the token Runware signs for them**: an AWS role, a Google workload identity provider, or an audience of your own. It holds no secret. The connectors belong to your organization and take no `environment`. An attachment binds one connector to one app, and takes `environment` like every app route, which omitted is `production`.

An attached connector has the `subject` its tokens use in that environment, and a `subjectPattern` for every app of the environment. **Copy them into your trust rule.** [OIDC connectors](https://runware.ai/docs/serverless/oidc-connectors) walks through the AWS, Google Cloud and generic setups.

A test exchanges a real token with the connector's cloud and returns what it answered, so you can check an `aws` or `gcp` trust setup before any code runs. [Test the trust setup](https://runware.ai/docs/serverless/oidc-connectors#test-the-trust-setup) covers the outcomes.

> [!NOTE]
> An app holds **at most one connector of each kind**, and a second returns `409`. While a connector is attached, the variables it sets on the worker are reserved on that app, so setting one as an environment variable or a secret returns `422`. `GOOGLE_APPLICATION_CREDENTIALS` and `RUNWARE_OIDC_CONFIG_DIGEST` are reserved on every app, with or without a connector.

## List connectors

GETapi.serverless.runware.ai/v1/oidc-connectors

### [Request](#list-oidc-connectors-request)

Query

### [limit](#list-oidc-connectors-query-limit)

- **Type**: `integer`
- **Format**: `int32`
- **Min**: `1`
- **Max**: `100`
- **Default**: `20`

Maximum number of items to return.

### [cursor](#list-oidc-connectors-query-cursor)

- **Type**: `string`

Opaque pagination cursor returned by a previous call, as `nextCursor` or, on the operations that offer one, `prevCursor`.

### [Response](#list-oidc-connectors-response)

### [nextCursor](#list-oidc-connectors-response-nextcursor)

- **Type**: `string (nullable)`

Cursor for the next page. Null when there are no more items.

### [data](#list-oidc-connectors-response-data)

- **Type**: `object[] (12 properties)`

#### [id](#list-oidc-connectors-response-data-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [name](#list-oidc-connectors-response-data-name)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

#### [kind](#list-oidc-connectors-response-data-kind)

- **Type**: `string`
- **Required**: true

The provider an OIDC connector authenticates to. Fixed once created.

**Possible values**: `aws` `gcp` `generic`

#### [audience](#list-oidc-connectors-response-data-audience)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

#### [aws](#list-oidc-connectors-response-data-aws)

- **Type**: `object (1 property)`

##### [roleArn](#list-oidc-connectors-response-data-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

#### [gcp](#list-oidc-connectors-response-data-gcp)

- **Type**: `object (2 properties)`

##### [workloadIdentityProvider](#list-oidc-connectors-response-data-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

##### [serviceAccountEmail](#list-oidc-connectors-response-data-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

#### [issuer](#list-oidc-connectors-response-data-issuer)

- **Type**: `string`

The token's `iss`: the URL a provider fetches the issuer's discovery document and keys from. Register it as the OIDC identity provider (AWS) or the provider's issuer (GCP). Absent where this environment has no OIDC issuer.

#### [createdAt](#list-oidc-connectors-response-data-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

#### [updatedAt](#list-oidc-connectors-response-data-updatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [Errors](#list-oidc-connectors-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Create a connector

POSTapi.serverless.runware.ai/v1/oidc-connectors

Creates an organization-scoped OIDC connector: the external provider an app's workers authenticate to with a short-lived token the platform signs, instead of a stored credential. A connector holds no secret. Attach it to an app with `POST /v1/apps/{appId}/oidc-connectors`. An app holds at most one connector of each kind. `kind` is fixed once created. `aws` takes the IAM role to assume, and the worker gets `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE`, which the AWS SDKs read unchanged. `gcp` takes the Workload Identity Federation provider, and optionally a service account to impersonate, and the worker gets `GOOGLE_APPLICATION_CREDENTIALS` naming an `external_account` configuration, which `google-auth` reads unchanged. `generic` takes only an audience, and the worker gets the token file and `RUNWARE_OIDC_TOKEN_FILE`. The token's `iss` is `issuer` on the response, its `aud` is `audience`, and its `sub` is `worker:org:<organization uuid>:env:<environment uuid>:app:<app id>`, for example `worker:org:0190a6a8-0000-7000-8000-00000000000a:env:0190a6a8-0000-7000-8000-0000000000e1:app:my-app`. The environment is the one the app runs in, by its immutable id, so a copy of the app in another environment has another subject. An AWS trust policy `StringEquals` on the attached connector's `subject` matches that app in that environment only; an app id deleted and created again in the same environment matches the same policy. A trust rule must check `sub`, or `org_id` where the verifier reads claims: `aud` does not separate organizations. The token also carries `org_id`, `environment_id`, `app_id`, `deployment_id`, `worker` and `connector` claims, which a GCP attribute condition or a generic verifier can pin further. It lives at most an hour; do not depend on an exact lifetime. Returns `409` if the name is already in use.

### [Request](#create-oidc-connector-request)

Body

### [name](#create-oidc-connector-body-name)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

### [kind](#create-oidc-connector-body-kind)

- **Type**: `string`
- **Required**: true

The provider an OIDC connector authenticates to. Fixed once created.

**Allowed values**: `aws` `gcp` `generic`

### [audience](#create-oidc-connector-body-audience)

- **Type**: `string`
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

### [aws](#create-oidc-connector-body-aws)

- **Type**: `object (1 property)`

#### [roleArn](#create-oidc-connector-body-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

### [gcp](#create-oidc-connector-body-gcp)

- **Type**: `object (2 properties)`

#### [workloadIdentityProvider](#create-oidc-connector-body-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

#### [serviceAccountEmail](#create-oidc-connector-body-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

### [Response](#create-oidc-connector-response)

### [id](#create-oidc-connector-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [name](#create-oidc-connector-response-name)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

### [kind](#create-oidc-connector-response-kind)

- **Type**: `string`
- **Required**: true

The provider an OIDC connector authenticates to. Fixed once created.

**Possible values**: `aws` `gcp` `generic`

### [audience](#create-oidc-connector-response-audience)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

### [aws](#create-oidc-connector-response-aws)

- **Type**: `object (1 property)`

#### [roleArn](#create-oidc-connector-response-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

### [gcp](#create-oidc-connector-response-gcp)

- **Type**: `object (2 properties)`

#### [workloadIdentityProvider](#create-oidc-connector-response-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

#### [serviceAccountEmail](#create-oidc-connector-response-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

### [issuer](#create-oidc-connector-response-issuer)

- **Type**: `string`

The token's `iss`: the URL a provider fetches the issuer's discovery document and keys from. Register it as the OIDC identity provider (AWS) or the provider's issuer (GCP). Absent where this environment has no OIDC issuer.

### [createdAt](#create-oidc-connector-response-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [updatedAt](#create-oidc-connector-response-updatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [Errors](#create-oidc-connector-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">501</code></td><td data-rw-cid-pz7tphoj="true">OIDC connectors are not available in this environment: it has no OIDC issuer. Creating, updating and attaching a connector answer this before they read or write anything; listing, reading, deleting and detaching keep working, so a connector can always be removed.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Get a connector

GETapi.serverless.runware.ai/v1/oidc-connectors/{connectorName}

### [Request](#get-oidc-connector-request)

Path

### [connectorName](#get-oidc-connector-path-connectorname)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the authenticated organization.

### [Response](#get-oidc-connector-response)

### [id](#get-oidc-connector-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [name](#get-oidc-connector-response-name)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

### [kind](#get-oidc-connector-response-kind)

- **Type**: `string`
- **Required**: true

The provider an OIDC connector authenticates to. Fixed once created.

**Possible values**: `aws` `gcp` `generic`

### [audience](#get-oidc-connector-response-audience)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

### [aws](#get-oidc-connector-response-aws)

- **Type**: `object (1 property)`

#### [roleArn](#get-oidc-connector-response-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

### [gcp](#get-oidc-connector-response-gcp)

- **Type**: `object (2 properties)`

#### [workloadIdentityProvider](#get-oidc-connector-response-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

#### [serviceAccountEmail](#get-oidc-connector-response-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

### [issuer](#get-oidc-connector-response-issuer)

- **Type**: `string`

The token's `iss`: the URL a provider fetches the issuer's discovery document and keys from. Register it as the OIDC identity provider (AWS) or the provider's issuer (GCP). Absent where this environment has no OIDC issuer.

### [createdAt](#get-oidc-connector-response-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [updatedAt](#get-oidc-connector-response-updatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [Errors](#get-oidc-connector-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Update a connector

PUTapi.serverless.runware.ai/v1/oidc-connectors/{connectorName}

Replaces the connector's audience and provider fields; the name and `kind` stay. Rolls every live deployment that attaches it in place, so its workers get the new configuration. Running workers keep the old configuration until they roll. `activeVersionId` does not move. See `AppEvent`. No rollout starts for a deployment that is not live; it picks up the change on its next rollout. A deployment that already has a rollout in progress rolls again on its own once that rollout finishes, and records an event that says so. Send the `ETag` from `GET /v1/oidc-connectors/{connectorName}` as `If-Match` to guard a read-modify-write: the update applies only if the connector is unchanged since that read, and otherwise returns `412` with nothing changed and nothing rolled. `If-Match: *` applies whenever the connector exists. Without `If-Match` the update applies unconditionally, as before. A connector that does not exist returns `404` for a well-formed `If-Match` or none. A malformed `If-Match` returns `400` before the connector is looked up, so a missing connector with one also returns `400`.

### [Request](#update-oidc-connector-request)

Path

### [connectorName](#update-oidc-connector-path-connectorname)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the authenticated organization.

Header

### [If-Match](#update-oidc-connector-header-if-match)

- **Type**: `string`
- **Max**: `256`

Optional precondition on the resource's current state: the `ETag` from an earlier read of it. The request applies only while that is still the resource's current `ETag`; otherwise it returns `412` and changes nothing. `*` matches any existing resource, so it adds no check beyond the resource existing. Without the header the request applies unconditionally. Send one entity-tag exactly as received, quotes included. A `W/` prefix is accepted and ignored: a proxy that compresses the response may weaken the `ETag` to `W/"..."`, and that weak form names the same state as the strong one. A value that is not `*` or one quoted entity-tag, optionally `W/`\-prefixed (a comma-separated list in one header, a bare token), returns `400`. So does a quoted tag this API never issued, such as `"abc"` or `"-5"`. A value longer than 256 characters is refused by request validation with `422`, before the header is read as an entity-tag.

Body

### [audience](#update-oidc-connector-body-audience)

- **Type**: `string`
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

### [aws](#update-oidc-connector-body-aws)

- **Type**: `object (1 property)`

#### [roleArn](#update-oidc-connector-body-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

### [gcp](#update-oidc-connector-body-gcp)

- **Type**: `object (2 properties)`

#### [workloadIdentityProvider](#update-oidc-connector-body-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

#### [serviceAccountEmail](#update-oidc-connector-body-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

### [Response](#update-oidc-connector-response)

### [id](#update-oidc-connector-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [name](#update-oidc-connector-response-name)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

### [kind](#update-oidc-connector-response-kind)

- **Type**: `string`
- **Required**: true

The provider an OIDC connector authenticates to. Fixed once created.

**Possible values**: `aws` `gcp` `generic`

### [audience](#update-oidc-connector-response-audience)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

### [aws](#update-oidc-connector-response-aws)

- **Type**: `object (1 property)`

#### [roleArn](#update-oidc-connector-response-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

### [gcp](#update-oidc-connector-response-gcp)

- **Type**: `object (2 properties)`

#### [workloadIdentityProvider](#update-oidc-connector-response-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

#### [serviceAccountEmail](#update-oidc-connector-response-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

### [issuer](#update-oidc-connector-response-issuer)

- **Type**: `string`

The token's `iss`: the URL a provider fetches the issuer's discovery document and keys from. Register it as the OIDC identity provider (AWS) or the provider's issuer (GCP). Absent where this environment has no OIDC issuer.

### [createdAt](#update-oidc-connector-response-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [updatedAt](#update-oidc-connector-response-updatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [Errors](#update-oidc-connector-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">412</code></td><td data-rw-cid-pz7tphoj="true">An <code class="component-Code">If-Match</code> precondition did not hold: the resource changed since the <code class="component-Code">ETag</code> the client sent, so nothing was changed. Read the resource again, reapply the change to the fresh state and retry with the new <code class="component-Code">ETag</code>.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">501</code></td><td data-rw-cid-pz7tphoj="true">OIDC connectors are not available in this environment: it has no OIDC issuer. Creating, updating and attaching a connector answer this before they read or write anything; listing, reading, deleting and detaching keep working, so a connector can always be removed.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Delete a connector

DELETEapi.serverless.runware.ai/v1/oidc-connectors/{connectorName}

Deletes the connector. Returns `409` while any app still attaches it: detach it from each app first.

### [Request](#delete-oidc-connector-request)

Path

### [connectorName](#delete-oidc-connector-path-connectorname)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the authenticated organization.

### [Errors](#delete-oidc-connector-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## List an app's connectors

GETapi.serverless.runware.ai/v1/apps/{appId}/oidc-connectors

### [Request](#list-app-oidc-connectors-request)

Path

### [appId](#list-app-oidc-connectors-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

Query

### [environment](#list-app-oidc-connectors-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [Response](#list-app-oidc-connectors-response)

### [data](#list-app-oidc-connectors-response-data)

- **Type**: `object[] (14 properties)`
- **Required**: true
- **Max items**: `3`

#### [id](#list-app-oidc-connectors-response-data-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [name](#list-app-oidc-connectors-response-data-name)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

#### [kind](#list-app-oidc-connectors-response-data-kind)

- **Type**: `string`
- **Required**: true

The provider an OIDC connector authenticates to. Fixed once created.

**Possible values**: `aws` `gcp` `generic`

#### [audience](#list-app-oidc-connectors-response-data-audience)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

#### [aws](#list-app-oidc-connectors-response-data-aws)

- **Type**: `object (1 property)`

##### [roleArn](#list-app-oidc-connectors-response-data-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

#### [gcp](#list-app-oidc-connectors-response-data-gcp)

- **Type**: `object (2 properties)`

##### [workloadIdentityProvider](#list-app-oidc-connectors-response-data-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

##### [serviceAccountEmail](#list-app-oidc-connectors-response-data-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

#### [issuer](#list-app-oidc-connectors-response-data-issuer)

- **Type**: `string`

The token's `iss`: the URL a provider fetches the issuer's discovery document and keys from. Register it as the OIDC identity provider (AWS) or the provider's issuer (GCP). Absent where this environment has no OIDC issuer.

#### [createdAt](#list-app-oidc-connectors-response-data-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

#### [updatedAt](#list-app-oidc-connectors-response-data-updatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

#### [subject](#list-app-oidc-connectors-response-data-subject)

- **Type**: `string`
- **Required**: true

The exact `sub` of this app's tokens in the environment addressed, for a `StringEquals` trust condition: `worker:org:<organization uuid>:env:<environment uuid>:app:<app id>`. An app id deleted and created again in the same environment has the same one.

#### [subjectPattern](#list-app-oidc-connectors-response-data-subjectpattern)

- **Type**: `string`
- **Required**: true

A `StringLike` condition that matches every app of the organization in this environment and nothing in another environment, `worker:org:<organization uuid>:env:<environment uuid>:*`.

### [Errors](#list-app-oidc-connectors-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Attach a connector to an app

POSTapi.serverless.runware.ai/v1/apps/{appId}/oidc-connectors

Attaches an organization OIDC connector to an app and rolls the app's live deployment in place, so its workers start getting a token. `activeVersionId` does not move. See `AppEvent`. No rollout starts when the deployment is not live; the workers pick up the connector on its next rollout. A deployment that already has a rollout in progress rolls again on its own once that rollout finishes, and records an event that says so. An app holds at most one connector of each kind; a second of the same kind, or the same one twice, returns `409`. A connector reserves the env names it sets on the worker for as long as it is attached: `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE` for `aws`, `RUNWARE_OIDC_TOKEN_FILE` for `generic`. Attaching to an app that already has a plain environment variable or an attached secret under one of them returns `422`, and setting one on an app that has a connector of that kind returns `422` too. Whatever else sets one of them, such as an older version the app is pinned to, the worker gets the connector's value. An app with no connector of that kind may use those names. `GOOGLE_APPLICATION_CREDENTIALS`, which a `gcp` connector sets, and `RUNWARE_OIDC_CONFIG_DIGEST`, which every connector sets, are reserved on every app, connector or not, and always return `422`.

### [Request](#attach-app-oidc-connector-request)

Path

### [appId](#attach-app-oidc-connector-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

Query

### [environment](#attach-app-oidc-connector-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

Body

### [connectorName](#attach-app-oidc-connector-body-connectorname)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

### [Response](#attach-app-oidc-connector-response)

### [id](#attach-app-oidc-connector-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [name](#attach-app-oidc-connector-response-name)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the organization. `site-store` is reserved for a platform connector.

### [kind](#attach-app-oidc-connector-response-kind)

- **Type**: `string`
- **Required**: true

The provider an OIDC connector authenticates to. Fixed once created.

**Possible values**: `aws` `gcp` `generic`

### [audience](#attach-app-oidc-connector-response-audience)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `256`

The token's `aud`. Defaults to `runware:<organization uuid>` for `aws`, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts with `runware:` is reserved: only the organization's own `runware:<organization uuid>` is accepted, and any other returns `422`. Always `//iam.googleapis.com/<workloadIdentityProvider>` for `gcp`, the audience Google's STS expects; any other value returns `422`. Required for `generic`.

### [aws](#attach-app-oidc-connector-response-aws)

- **Type**: `object (1 property)`

#### [roleArn](#attach-app-oidc-connector-response-aws-rolearn)

- **Type**: `string`
- **Required**: true
- **Max**: `2048`

The IAM role the worker assumes through `AssumeRoleWithWebIdentity`. Its trust policy names this platform's issuer as a federated principal.

### [gcp](#attach-app-oidc-connector-response-gcp)

- **Type**: `object (2 properties)`

#### [workloadIdentityProvider](#attach-app-oidc-connector-response-gcp-workloadidentityprovider)

- **Type**: `string`
- **Required**: true
- **Max**: `512`

The Workload Identity Federation provider's full resource name.

#### [serviceAccountEmail](#attach-app-oidc-connector-response-gcp-serviceaccountemail)

- **Type**: `string`
- **Max**: `256`

A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.

### [issuer](#attach-app-oidc-connector-response-issuer)

- **Type**: `string`

The token's `iss`: the URL a provider fetches the issuer's discovery document and keys from. Register it as the OIDC identity provider (AWS) or the provider's issuer (GCP). Absent where this environment has no OIDC issuer.

### [createdAt](#attach-app-oidc-connector-response-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [updatedAt](#attach-app-oidc-connector-response-updatedat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [subject](#attach-app-oidc-connector-response-subject)

- **Type**: `string`
- **Required**: true

The exact `sub` of this app's tokens in the environment addressed, for a `StringEquals` trust condition: `worker:org:<organization uuid>:env:<environment uuid>:app:<app id>`. An app id deleted and created again in the same environment has the same one.

### [subjectPattern](#attach-app-oidc-connector-response-subjectpattern)

- **Type**: `string`
- **Required**: true

A `StringLike` condition that matches every app of the organization in this environment and nothing in another environment, `worker:org:<organization uuid>:env:<environment uuid>:*`.

### [Errors](#attach-app-oidc-connector-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">501</code></td><td data-rw-cid-pz7tphoj="true">OIDC connectors are not available in this environment: it has no OIDC issuer. Creating, updating and attaching a connector answer this before they read or write anything; listing, reading, deleting and detaching keep working, so a connector can always be removed.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Detach a connector from an app

DELETEapi.serverless.runware.ai/v1/apps/{appId}/oidc-connectors/{connectorName}

Detaches the connector and rolls the app's live deployment in place, so its workers stop getting a token. Running workers keep the connector until they roll, and a token a worker already holds stays valid until it expires, at most an hour. `activeVersionId` does not move. See `AppEvent`. No rollout starts when the deployment is not live; the workers lose the connector on its next rollout. A deployment that already has a rollout in progress rolls again on its own once that rollout finishes, and records an event that says so.

### [Request](#detach-app-oidc-connector-request)

Path

### [appId](#detach-app-oidc-connector-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

### [connectorName](#detach-app-oidc-connector-path-connectorname)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the authenticated organization.

Query

### [environment](#detach-app-oidc-connector-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [Errors](#detach-app-oidc-connector-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Test a connector's trust setup

POSTapi.serverless.runware.ai/v1/apps/{appId}/oidc-connectors/{connectorName}/test

Starts a test of the trust setup between the app and the connector's cloud, without deploying any code. The platform runs a short-lived probe as a worker of the app, with no customer code: it gets the app's token like a worker does and exchanges it with the cloud, Google STS (and service account impersonation when the connector names one) or AWS `AssumeRoleWithWebIdentity`. The probe obtains real, short-lived credentials and discards them; no token or credential is returned, stored or logged. On AWS the session name is `runware-connector-test-<test id>`, so a test shows in CloudTrail. Answers `202` with the test in `pending`; poll `GET /v1/apps/{appId}/oidc-connectors/{connectorName}/tests/{testId}` for the result, which is normally there within a minute and always within two. The connector must be attached to the app in the environment, and be of kind `aws` or `gcp`: a `generic` connector has no cloud to exchange with and answers `422`. One test of a connector runs at a time for each app and environment; a second answers `409`. An organization starts at most 20 tests an hour, counting those running and those that ended `ok` or `cloud_error`, and at most 60 an hour that end `platform_error`; past either, `429`.

### [Request](#test-app-oidc-connector-request)

Path

### [appId](#test-app-oidc-connector-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

### [connectorName](#test-app-oidc-connector-path-connectorname)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the authenticated organization.

Query

### [environment](#test-app-oidc-connector-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [Response](#test-app-oidc-connector-response)

### [id](#test-app-oidc-connector-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [status](#test-app-oidc-connector-response-status)

- **Type**: `string`
- **Required**: true

Where a test is. `ok` and `cloud_error` are the trust setup's own answer: the cloud accepted the token, or refused it with the error in `code` and `message`. `platform_error` means the platform could not run the test (see `reason`) and says nothing about the trust setup.

**Possible values**: `pending` `ok` `cloud_error` `platform_error`

### [reason](#test-app-oidc-connector-response-reason)

- **Type**: `string`

Why the platform could not run a test, present only with `platform_error`. `unconfigured`: this environment cannot run tests. `unschedulable`: the probe could not be placed. `image_pull`: the probe's image could not be pulled. `deadline`: the test did not finish in time. `issuer_refused`: the platform's issuer would not sign the app's token. `probe_failed`: the probe could not finish for a reason that says nothing about the trust setup, such as a cloud error on the provider's side or throttling. `tenancy_not_ready`: the organization's workers cannot run yet. `deployer_unavailable`: the platform could not start the test.

**Possible values**: `unconfigured` `unschedulable` `image_pull` `deadline` `issuer_refused` `probe_failed` `tenancy_not_ready` `deployer_unavailable`

### [stage](#test-app-oidc-connector-response-stage)

- **Type**: `string`

Where the probe was when it was refused: `issuer` (getting the app's token), `sts` (Google STS), `impersonation` (Google service account impersonation) or `assume_role` (AWS).

**Possible values**: `issuer` `sts` `impersonation` `assume_role`

### [code](#test-app-oidc-connector-response-code)

- **Type**: `string`
- **Max**: `64`

On `cloud_error`, the cloud's own error code, such as `invalid_target` or `unauthorized_client` from Google or `AccessDenied` from AWS, or `unknown`. On `platform_error: issuer_refused`, the platform's issuer's RFC 6749 code, such as `invalid_grant`: the platform refused to sign the app's token, and the customer's cloud was not asked.

### [message](#test-app-oidc-connector-response-message)

- **Type**: `string`
- **Max**: `512`

On `cloud_error`, the cloud's error message, or `cloud error message withheld` when it contained a token or a credential. On `platform_error`, the platform's description of what went wrong, such as `Google STS answered 503`: it is not the cloud's verdict on the trust setup.

### [troubleshooting](#test-app-oidc-connector-response-troubleshooting)

- **Type**: `string`

What a `cloud_error` with this `code` usually means and what to check.

### [identity](#test-app-oidc-connector-response-identity)

- **Type**: `string`
- **Max**: `1024`

On `ok`, what the cloud accepted the token as: the assumed role's ARN (AWS) or the impersonated service account (GCP). Absent for a GCP connector with no service account.

### [createdAt](#test-app-oidc-connector-response-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [deadlineAt](#test-app-oidc-connector-response-deadlineat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

When a test still `pending` turns into `platform_error` with `deadline`.

### [finishedAt](#test-app-oidc-connector-response-finishedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#test-app-oidc-connector-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">429</code></td><td data-rw-cid-pz7tphoj="true">The organization has started as many OIDC connector tests as an hour allows. <code class="component-Code">Retry-After</code> says when the next one may start.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">501</code></td><td data-rw-cid-pz7tphoj="true">OIDC connectors are not available in this environment: it has no OIDC issuer. Creating, updating and attaching a connector answer this before they read or write anything; listing, reading, deleting and detaching keep working, so a connector can always be removed.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Get a test

GETapi.serverless.runware.ai/v1/apps/{appId}/oidc-connectors/{connectorName}/tests/{testId}

A test started with `POST /v1/apps/{appId}/oidc-connectors/{connectorName}/test`. Tests are kept for 24 hours.

### [Request](#get-app-oidc-connector-test-request)

Path

### [appId](#get-app-oidc-connector-test-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

### [connectorName](#get-app-oidc-connector-test-path-connectorname)

- **Type**: `string`
- **Required**: true
- **Min**: `2`
- **Max**: `63`

OIDC connector name, unique within the authenticated organization.

### [testId](#get-app-oidc-connector-test-path-testid)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

The test's id, from the `202` that started it.

Query

### [environment](#get-app-oidc-connector-test-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [Response](#get-app-oidc-connector-test-response)

### [id](#get-app-oidc-connector-test-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [status](#get-app-oidc-connector-test-response-status)

- **Type**: `string`
- **Required**: true

Where a test is. `ok` and `cloud_error` are the trust setup's own answer: the cloud accepted the token, or refused it with the error in `code` and `message`. `platform_error` means the platform could not run the test (see `reason`) and says nothing about the trust setup.

**Possible values**: `pending` `ok` `cloud_error` `platform_error`

### [reason](#get-app-oidc-connector-test-response-reason)

- **Type**: `string`

Why the platform could not run a test, present only with `platform_error`. `unconfigured`: this environment cannot run tests. `unschedulable`: the probe could not be placed. `image_pull`: the probe's image could not be pulled. `deadline`: the test did not finish in time. `issuer_refused`: the platform's issuer would not sign the app's token. `probe_failed`: the probe could not finish for a reason that says nothing about the trust setup, such as a cloud error on the provider's side or throttling. `tenancy_not_ready`: the organization's workers cannot run yet. `deployer_unavailable`: the platform could not start the test.

**Possible values**: `unconfigured` `unschedulable` `image_pull` `deadline` `issuer_refused` `probe_failed` `tenancy_not_ready` `deployer_unavailable`

### [stage](#get-app-oidc-connector-test-response-stage)

- **Type**: `string`

Where the probe was when it was refused: `issuer` (getting the app's token), `sts` (Google STS), `impersonation` (Google service account impersonation) or `assume_role` (AWS).

**Possible values**: `issuer` `sts` `impersonation` `assume_role`

### [code](#get-app-oidc-connector-test-response-code)

- **Type**: `string`
- **Max**: `64`

On `cloud_error`, the cloud's own error code, such as `invalid_target` or `unauthorized_client` from Google or `AccessDenied` from AWS, or `unknown`. On `platform_error: issuer_refused`, the platform's issuer's RFC 6749 code, such as `invalid_grant`: the platform refused to sign the app's token, and the customer's cloud was not asked.

### [message](#get-app-oidc-connector-test-response-message)

- **Type**: `string`
- **Max**: `512`

On `cloud_error`, the cloud's error message, or `cloud error message withheld` when it contained a token or a credential. On `platform_error`, the platform's description of what went wrong, such as `Google STS answered 503`: it is not the cloud's verdict on the trust setup.

### [troubleshooting](#get-app-oidc-connector-test-response-troubleshooting)

- **Type**: `string`

What a `cloud_error` with this `code` usually means and what to check.

### [identity](#get-app-oidc-connector-test-response-identity)

- **Type**: `string`
- **Max**: `1024`

On `ok`, what the cloud accepted the token as: the assumed role's ARN (AWS) or the impersonated service account (GCP). Absent for a GCP connector with no service account.

### [createdAt](#get-app-oidc-connector-test-response-createdat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

### [deadlineAt](#get-app-oidc-connector-test-response-deadlineat)

- **Type**: `string (date-time)`
- **Required**: true
- **Format**: `date-time`

When a test still `pending` turns into `platform_error` with `deadline`.

### [finishedAt](#get-app-oidc-connector-test-response-finishedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#get-app-oidc-connector-test-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>