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
Request
Response
nextCursor
stringnullableCursor 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: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
kind
stringrequiredThe provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values
audience
stringrequiredmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
issuer
stringThe 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
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
name
stringrequiredmin: 2max: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
kind
stringrequiredThe provider an OIDC connector authenticates to. Fixed once created.
Allowed values3 values
audience
stringmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
Response
id
string (uuid)requiredUUID v4
name
stringrequiredmin: 2max: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
kind
stringrequiredThe provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values
audience
stringrequiredmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
issuer
stringThe 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
Request
connectorName
stringrequiredmin: 2max: 63OIDC connector name, unique within the authenticated organization.
Response
id
string (uuid)requiredUUID v4
name
stringrequiredmin: 2max: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
kind
stringrequiredThe provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values
audience
stringrequiredmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
issuer
stringThe 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
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
connectorName
stringrequiredmin: 2max: 63OIDC connector name, unique within the authenticated organization.
If-Match
stringmax: 256Optional precondition on the resource's current state: the
ETagfrom an earlier read of it. The request applies only while that is still the resource's currentETag; otherwise it returns412and 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. AW/prefix is accepted and ignored: a proxy that compresses the response may weaken theETagtoW/"...", and that weak form names the same state as the strong one. A value that is not*or one quoted entity-tag, optionallyW/-prefixed (a comma-separated list in one header, a bare token), returns400. 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 with422, before the header is read as an entity-tag.
audience
stringmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
Response
id
string (uuid)requiredUUID v4
name
stringrequiredmin: 2max: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
kind
stringrequiredThe provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values
audience
stringrequiredmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
issuer
stringThe 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 |
412 | An 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.
|
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
Deletes the connector. Returns 409 while any app still attaches it: detach it from each app first.
Request
connectorName
stringrequiredmin: 2max: 63OIDC 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
Request
appId
stringrequiredmin: 6max: 30Immutable app identifier, unique among the authenticated organization's live apps in one environment. The
environmentquery parameter selects which copy the request addresses.
environment
stringmin: 1max: 63The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address:
appIdtogether withenvironmentselects 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 meansproduction. A name the organization has no live environment under returns404.
Response
data
object[]requiredmax items: 3Array items11 properties each
id
string (uuid)requiredUUID v4
name
stringrequiredmin: 2max: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
kind
stringrequiredThe provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values
audience
stringrequiredmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
issuer
stringThe 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
stringrequiredThe exact
subof this app's tokens in the environment addressed, for aStringEqualstrust 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
stringrequiredA
StringLikecondition 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
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
appId
stringrequiredmin: 6max: 30Immutable app identifier, unique among the authenticated organization's live apps in one environment. The
environmentquery parameter selects which copy the request addresses.
environment
stringmin: 1max: 63The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address:
appIdtogether withenvironmentselects 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 meansproduction. A name the organization has no live environment under returns404.
connectorName
stringrequiredmin: 2max: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
Response
id
string (uuid)requiredUUID v4
name
stringrequiredmin: 2max: 63OIDC connector name, unique within the organization.
site-storeis reserved for a platform connector.
kind
stringrequiredThe provider an OIDC connector authenticates to. Fixed once created.
Possible values3 values
audience
stringrequiredmin: 1max: 256The token's
aud. Defaults torunware:<organization uuid>foraws, one value per organization, which the IAM OIDC provider must list as a client ID. An audience that starts withrunware:is reserved: only the organization's ownrunware:<organization uuid>is accepted, and any other returns422. Always//iam.googleapis.com/<workloadIdentityProvider>forgcp, the audience Google's STS expects; any other value returns422. Required forgeneric.
aws
objectProperties1 property
roleArn
stringrequiredmax: 2048The IAM role the worker assumes through
AssumeRoleWithWebIdentity. Its trust policy names this platform's issuer as a federated principal.
gcp
objectProperties2 properties
workloadIdentityProvider
stringrequiredmax: 512The Workload Identity Federation provider's full resource name.
serviceAccountEmail
stringmax: 256A service account to impersonate after the exchange. Omitted, the federated principal is granted access directly.
issuer
stringThe 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
stringrequiredThe exact
subof this app's tokens in the environment addressed, for aStringEqualstrust 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
stringrequiredA
StringLikecondition 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 |
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
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
appId
stringrequiredmin: 6max: 30Immutable app identifier, unique among the authenticated organization's live apps in one environment. The
environmentquery parameter selects which copy the request addresses.
connectorName
stringrequiredmin: 2max: 63OIDC connector name, unique within the authenticated organization.
environment
stringmin: 1max: 63The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address:
appIdtogether withenvironmentselects 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 meansproduction. A name the organization has no live environment under returns404.
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 |
Test a connector's trust setup
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
appId
stringrequiredmin: 6max: 30Immutable app identifier, unique among the authenticated organization's live apps in one environment. The
environmentquery parameter selects which copy the request addresses.
connectorName
stringrequiredmin: 2max: 63OIDC connector name, unique within the authenticated organization.
environment
stringmin: 1max: 63The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address:
appIdtogether withenvironmentselects 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 meansproduction. A name the organization has no live environment under returns404.
Response
id
string (uuid)requiredUUID v4
status
stringrequiredWhere a test is.
okandcloud_errorare the trust setup's own answer: the cloud accepted the token, or refused it with the error incodeandmessage.platform_errormeans the platform could not run the test (seereason) and says nothing about the trust setup.Possible values4 values
reason
stringWhy 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
stringWhere the probe was when it was refused:
issuer(getting the app's token),sts(Google STS),impersonation(Google service account impersonation) orassume_role(AWS).Possible values4 values
code
stringmax: 64On
cloud_error, the cloud's own error code, such asinvalid_targetorunauthorized_clientfrom Google orAccessDeniedfrom AWS, orunknown. Onplatform_error: issuer_refused, the platform's issuer's RFC 6749 code, such asinvalid_grant: the platform refused to sign the app's token, and the customer's cloud was not asked.
message
stringmax: 512On
cloud_error, the cloud's error message, orcloud error message withheldwhen it contained a token or a credential. Onplatform_error, the platform's description of what went wrong, such asGoogle STS answered 503: it is not the cloud's verdict on the trust setup.
troubleshooting
stringWhat a
cloud_errorwith thiscodeusually means and what to check.
identity
stringmax: 1024On
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-timeWhen a test still
pendingturns intoplatform_errorwithdeadline.
finishedAt
string (date-time)date-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 |
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.
|
429 | The organization has started as many OIDC connector tests as an hour allows. Retry-After says when the next one may start.
|
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 test
A test started with POST /v1/apps/{appId}/oidc-connectors/{connectorName}/test. Tests are kept for 24 hours.
Request
appId
stringrequiredmin: 6max: 30Immutable app identifier, unique among the authenticated organization's live apps in one environment. The
environmentquery parameter selects which copy the request addresses.
connectorName
stringrequiredmin: 2max: 63OIDC connector name, unique within the authenticated organization.
testId
string (uuid)requiredUUID v4The test's id, from the
202that started it.
environment
stringmin: 1max: 63The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address:
appIdtogether withenvironmentselects 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 meansproduction. A name the organization has no live environment under returns404.
Response
id
string (uuid)requiredUUID v4
status
stringrequiredWhere a test is.
okandcloud_errorare the trust setup's own answer: the cloud accepted the token, or refused it with the error incodeandmessage.platform_errormeans the platform could not run the test (seereason) and says nothing about the trust setup.Possible values4 values
reason
stringWhy 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
stringWhere the probe was when it was refused:
issuer(getting the app's token),sts(Google STS),impersonation(Google service account impersonation) orassume_role(AWS).Possible values4 values
code
stringmax: 64On
cloud_error, the cloud's own error code, such asinvalid_targetorunauthorized_clientfrom Google orAccessDeniedfrom AWS, orunknown. Onplatform_error: issuer_refused, the platform's issuer's RFC 6749 code, such asinvalid_grant: the platform refused to sign the app's token, and the customer's cloud was not asked.
message
stringmax: 512On
cloud_error, the cloud's error message, orcloud error message withheldwhen it contained a token or a credential. Onplatform_error, the platform's description of what went wrong, such asGoogle STS answered 503: it is not the cloud's verdict on the trust setup.
troubleshooting
stringWhat a
cloud_errorwith thiscodeusually means and what to check.
identity
stringmax: 1024On
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-timeWhen a test still
pendingturns intoplatform_errorwithdeadline.
finishedAt
string (date-time)date-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 |