OIDC connectors

Manage your organization's OIDC connectors and attach them to the apps whose workers authenticate with them.

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 carries 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 walks through the AWS, Google Cloud and generic setups.

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

Query

limit integerint32min: 1max: 100default: 20: Maximum number of items to return.

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

Response

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

data object[]

Array items9 properties each

id string (uuid)requiredUUID v4

name stringrequiredmin: 2max: 63: OIDC connector name, unique within the organization.

kind stringrequired: The provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values

audience stringrequiredmin: 1max: 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 object

Properties1 property

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

gcp object

Properties2 properties

workloadIdentityProvider stringrequiredmax: 512: The Workload Identity Federation provider's full resource name.

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

issuer 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 string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

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

Body

name stringrequiredmin: 2max: 63: OIDC connector name, unique within the organization.

kind stringrequired: The provider an OIDC connector authenticates to. Fixed once created.
Allowed values3 values

audience stringmin: 1max: 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 object

Properties1 property

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

gcp object

Properties2 properties

workloadIdentityProvider stringrequiredmax: 512: The Workload Identity Federation provider's full resource name.

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

Response

id string (uuid)requiredUUID v4

name stringrequiredmin: 2max: 63: OIDC connector name, unique within the organization.

kind stringrequired: The provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values

audience stringrequiredmin: 1max: 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 object

Properties1 property

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

gcp object

Properties2 properties

workloadIdentityProvider stringrequiredmax: 512: The Workload Identity Federation provider's full resource name.

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

issuer 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 string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`409`	Resource already exists or the request conflicts with its current state
`413`	The request body exceeds its size limit: 10 MiB on `invoke-sync` and `invoke-async`, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. `detail` names the limit in bytes.
`415`	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 `application/json` that cannot be parsed returns `400`. One that parses and breaks the schema returns `422`. A body sent with no Content-Type is the same refusal.
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`501`	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.
`503`	A required service is temporarily unavailable

Get a connector

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

Request

Path

connectorName stringrequiredmin: 2max: 63: OIDC connector name, unique within the authenticated organization.

Response

id string (uuid)requiredUUID v4

name stringrequiredmin: 2max: 63: OIDC connector name, unique within the organization.

kind stringrequired: The provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values

audience stringrequiredmin: 1max: 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 object

Properties1 property

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

gcp object

Properties2 properties

workloadIdentityProvider stringrequiredmax: 512: The Workload Identity Federation provider's full resource name.

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

issuer 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 string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`404`	Resource not found
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

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. No rollout starts for a deployment that is not live or already has a rollout in progress; it picks up the change on its next rollout.

Request

Path

connectorName stringrequiredmin: 2max: 63: OIDC connector name, unique within the authenticated organization.

Body

audience stringmin: 1max: 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 object

Properties1 property

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

gcp object

Properties2 properties

workloadIdentityProvider stringrequiredmax: 512: The Workload Identity Federation provider's full resource name.

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

Response

id string (uuid)requiredUUID v4

name stringrequiredmin: 2max: 63: OIDC connector name, unique within the organization.

kind stringrequired: The provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values

audience stringrequiredmin: 1max: 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 object

Properties1 property

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

gcp object

Properties2 properties

workloadIdentityProvider stringrequiredmax: 512: The Workload Identity Federation provider's full resource name.

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

issuer 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 string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`404`	Resource not found
`413`	The request body exceeds its size limit: 10 MiB on `invoke-sync` and `invoke-async`, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. `detail` names the limit in bytes.
`415`	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 `application/json` that cannot be parsed returns `400`. One that parses and breaks the schema returns `422`. A body sent with no Content-Type is the same refusal.
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`501`	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.
`503`	A required service is temporarily unavailable

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

Path

connectorName stringrequiredmin: 2max: 63: OIDC connector name, unique within the authenticated organization.

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`404`	Resource not found
`409`	Resource already exists or the request conflicts with its current state
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

List an app's connectors

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

Request

Path

appId stringrequiredmin: 6max: 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 stringmin: 1max: 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 or log query that names no app covers the whole organization; one 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

data object[]requiredmax items: 3

Array items11 properties each

id string (uuid)requiredUUID v4

name stringrequiredmin: 2max: 63: OIDC connector name, unique within the organization.

kind stringrequired: The provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values

audience stringrequiredmin: 1max: 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 object

Properties1 property

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

gcp object

Properties2 properties

workloadIdentityProvider stringrequiredmax: 512: The Workload Identity Federation provider's full resource name.

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

issuer 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 string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

subject stringrequired: 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 stringrequired: 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

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`404`	Resource not found
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

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. No rollout starts when the deployment is not live or already has a rollout in progress; the workers pick up the connector on its next rollout. 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

Path

appId stringrequiredmin: 6max: 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 stringmin: 1max: 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 or log query that names no app covers the whole organization; one 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 stringrequiredmin: 2max: 63: OIDC connector name, unique within the organization.

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`404`	Resource not found
`409`	Resource already exists or the request conflicts with its current state
`413`	The request body exceeds its size limit: 10 MiB on `invoke-sync` and `invoke-async`, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. `detail` names the limit in bytes.
`415`	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 `application/json` that cannot be parsed returns `400`. One that parses and breaks the schema returns `422`. A body sent with no Content-Type is the same refusal.
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`501`	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.
`503`	A required service is temporarily unavailable

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. No rollout starts when the deployment is not live or already has a rollout in progress; the workers lose the connector on its next rollout.

Request

Path

appId stringrequiredmin: 6max: 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 stringrequiredmin: 2max: 63: OIDC connector name, unique within the authenticated organization.

Query

environment stringmin: 1max: 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 or log query that names no app covers the whole organization; one 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

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`404`	Resource not found
`422`	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 `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable