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 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 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 covers the outcomes.

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. site-store is reserved for a platform connector.

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

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
422The 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.
500Unexpected server error
503A 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. site-store is reserved for a platform connector.

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. site-store is reserved for a platform connector.

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

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
403Authenticated but not permitted to access this resource
409Resource already exists or the request conflicts with its current state
413The 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.
415The 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.
422The 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.
500Unexpected server error
501OIDC 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.
503A 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. site-store is reserved for a platform connector.

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

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
404Resource not found
422The 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.
500Unexpected server error
503A 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. 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

Path

connectorName

stringrequiredmin: 2max: 63

OIDC connector name, unique within the authenticated organization.

Header

If-Match

stringmax: 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

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. site-store is reserved for a platform connector.

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

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
403Authenticated but not permitted to access this resource
404Resource not found
412An If-Match precondition did not hold: the resource changed since the ETag the client sent, so nothing was changed. Read the resource again, reapply the change to the fresh state and retry with the new ETag.
413The 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.
415The 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.
422The 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.
500Unexpected server error
501OIDC 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.
503A 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

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
403Authenticated but not permitted to access this resource
404Resource not found
409Resource already exists or the request conflicts with its current state
422The 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.
500Unexpected server error
503A 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 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

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. site-store is reserved for a platform connector.

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

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
404Resource not found
422The 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.
500Unexpected server error
503A 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. 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

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 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

stringrequiredmin: 2max: 63

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

Response

id

string (uuid)requiredUUID v4

name

stringrequiredmin: 2max: 63

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

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

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
403Authenticated but not permitted to access this resource
404Resource not found
409Resource already exists or the request conflicts with its current state
413The 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.
415The 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.
422The 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.
500Unexpected server error
501OIDC 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.
503A 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. 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

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 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

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

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

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 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

id

string (uuid)requiredUUID v4

status

stringrequired

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 values4 values

reason

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 values8 values

stage

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 values4 values

code

stringmax: 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

stringmax: 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.

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

identity

stringmax: 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

string (date-time)requireddate-time

deadlineAt

string (date-time)requireddate-time

When a test still pending turns into platform_error with deadline.

finishedAt

string (date-time)date-time

Errors

StatusWhen
400The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns 422 instead.
401Missing or invalid credentials
403Authenticated but not permitted to access this resource
404Resource not found
409Resource already exists or the request conflicts with its current state
422The 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.
429The organization has started as many OIDC connector tests as an hour allows. Retry-After says when the next one may start.
500Unexpected server error
501OIDC 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.
503A required service is temporarily unavailable

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

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.

testId

string (uuid)requiredUUID v4

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

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 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

id

string (uuid)requiredUUID v4

status

stringrequired

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 values4 values

reason

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 values8 values

stage

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 values4 values

code

stringmax: 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

stringmax: 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.

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

identity

stringmax: 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

string (date-time)requireddate-time

deadlineAt

string (date-time)requireddate-time

When a test still pending turns into platform_error with deadline.

finishedAt

string (date-time)date-time

Errors

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