Skip to main content

Subscribing to APIs

Prerequisites

Before subscribing to an API, the API must already be exposed by another team. The provider must have completed both the specification registration and the API exposure. See Exposing APIs for details on the full exposure process.

Subscribing to an API grants your application access to an API exposed by another team. The subscription process is managed through Rover files and may require approval depending on the API provider's configuration.

Defining an API Subscription​

API subscriptions are declared in the subscriptions section of your Rover file:

apiVersion: tcp.ei.telekom.de/v1
kind: Rover
metadata:
  name: frontend-app
spec:
  zone: dataplane1
  subscriptions:
    - type: api
      basePath: /checkout/v1

Key Fields​

FieldDescription
basePathThe base path of the API you want to subscribe to. This must match an existing exposed API. It must be identical to the exposed API basePath, including case.

What Happens When You Subscribe​

When you apply a Rover file with an API subscription, the Control Plane:

  1. Creates an ApiSubscription resource linking your application to the target API
  2. The ApiSubscription handler verifies that both the Api resource and an active ApiExposure exist for the requested base path
  3. Creates an Approval resource (if the API requires approval)
  4. Waits for approval to be granted (for simple or foureyes strategies)
  5. Once approved, creates a Gateway ConsumeRoute that grants your application access to the API through the gateway
caution

If no active Api resource or ApiExposure exists for the requested base path, your subscription will remain in a pending state. Verify that the API provider has completed both the specification registration and the exposure.

note

If the API uses the auto approval strategy, access is granted immediately. For simple or foureyes strategies, you will need to wait for the API provider to approve your request. See Approvals for details.

API & Event Features​

Beyond the basic subscription, you can customize your API subscription with additional features such as failover and security.

tip

See API & Event Features for the full list of features and detailed configuration examples.

FeatureDescription
FailoverDefine fallback zones to try when the primary provider zone is unavailable.
SecurityProvide your own OAuth2 or basic authentication credentials instead of using platform-managed identity.

Checking Subscription Status​

You can check the status of your subscriptions using Rover-CTL:

roverctl get-info

The output will show the status of each subscription, including whether it is pending approval, granted, or rejected. See the Rover-CTL CLI Reference for more commands and options.

For local and cross-zone API subscriptions, the gateway URL is available while approval is pending, once the subscription prerequisites and zone configuration are valid. Kubernetes exposes it in status.gatewayUrl; Rover application info includes the existing tardis.stargate.url.api... variable. The URL uses the consumer zone's selected gateway preset, including consumer failover when configured. Cross-environment remote subscriptions are excluded.

A displayed URL is endpoint metadata, not proof of access. New access is provisioned only after approval is granted, and the subscription remains not ready while approval is pending.

Each application's variables array provides resolved connection values using the legacy variable names:

VariableValue
tardis.iris.client.idApplication client ID
tardis.iris.client.secretCurrent client secret
tardis.iris.client.secret.expirationCurrent secret expiration in UTC RFC 3339 format, when available
tardis.iris.url.issuerIdentity-provider issuer URL
tardis.iris.url.tokenResolved token endpoint URL
tardis.stargate.urlResolved gateway URL, including the selected consumer-failover preset
tardis.stargate.url.api.<basePath>Resolved API or agentic subscription endpoint; / in the base path becomes ., preserving case
tardis.horizon.subscription.id.<eventType>Event subscription identifier, when available
tardis.horizon.subscription.url.<eventType>Server-sent-event subscription URL, when available
tardis.horizon.event.urlEvent publish URL; same value as stargatePublishEventUrl. Uses the publish URL reported by the application's first event exposure that has one, otherwise the first non-hidden URL of the zone's selected Event gateway preset joined with /horizon/events/v1. Independent of tardis.stargate.url, which stays the API gateway URL
tardis.chevron.url, tardis.chevron.applicationPermission-query URL and application identifier, when configured

Variables whose source values are empty are omitted. The array is empty ([]) when no values are available; the Go implementation does not initialize fields with legacy placeholders. Legacy Cloudwalker and Raccoon variables are not generated from unsupported or unconfigured endpoints.

caution

The variables include the application's client secret. Treat get-info output as sensitive and do not write it to public logs or commit it to source control.

Next Steps​