Programmatic Access Using Service Accounts

Introduction

A Service Account can authenticate access to Tecton using either API key credentials or OAuth client credentials.

About API Key Credentials

An API key Service Account has a single API key. This key is long-lived and cannot be rotated. Requests to Tecton with API keys are authenticated using the Tecton-key scheme in the Authorization header of the request.

About OAuth Client Credentials

Public Preview

This feature is currently in Public Preview.

Please review the Limitations associated with this Public Preview feature.

Service Accounts can use short-lived access tokens by leveraging OAuth credentials. They authenticate to Tecton using the OAuth 2.0 client credentials grant type to get a short-lived access token which they can use to call Tecton APIs (e.g call Feature Services). These clients are designed to meet more strict security requirements and support client secret rotation. This authentication method offers enhanced security compared to long-lived API keys through:

• Automatic token expiration after 1 hour
• Programmatic client secret rotation

Create and Manage Service Accounts

A Service Account can have either an API Key or OAuth client credentials (but not both).

Create a Service Account

Use the HTTP API or CLI to create Service Accounts. Service Accounts with an API Key can also be created via the Web UI.

For example, to create an OAuth Service Account using the CLI:

tecton service-account create --oauth -n "<service-account-name>"

The output should resemble:

Save this Client Secret - you will not be able to get it again.
Client Secret: <SAVE THIS SECRET VALUE>

Make sure to save the new Service Account's API key or client secret somewhere secure immediately after creation, because you will not be able to retrieve it later.

Deactivate, Reactivate, Rename, and Delete Service Accounts

Service Accounts can be deactivated, reactivated, renamed, and deleted with the HTTP API or CLI or Web UI.

Permissions On the Service Account

The creator (owner) of the Service Account, as well as anyone with the Admin role, can perform administrative actions on the Service Account. This includes deactivating, deleting, and all OAuth client secret rotation actions.

Granting Access to Service Accounts

Service Accounts can be assigned any roles provided the caller has permission to do so. Refer to this page for the full list of assignable roles.

Authenticate to Feature Server

Your Service Account must have a role that allows it to read feature values from the Feature Service's workspace.

Authenticate using API Key

Requests to your Feature Service can be authenticated with an API key using the Tecton-key header:

curl -X POST https://<YOUR-TECTON-CLUSTER>.tecton.ai/api/v2/workspaces/<YOUR-WORKSPACE>/feature-services/<FEATURE-SERVICE-NAME>/get-features\
-H "Authorization: Tecton-key <YOUR-API-KEY>" -d '{
  "params": {
    "workspaceName": "<YOUR-WORKSPACE>",
    "featureServiceName": "<FEATURE-SERVICE-NAME>",
    "requestContextMap": {
      "amt": 101 # replace with your request body
    }
  }
}'

Authenticate with OAuth

OAuth Client Credentials cannot be used to call Tecton's APIs directly. They must first be exchanged for an access token, which can then be used to call the APIs.

Retrieve OAuth Access Token

To retrieve an access token for your Service Account, call the tokens endpoint with the everything scope and provide the Service Account ID and an active client secret value in the request body. The everything scope includes the Service Account's ability to call Feature Server and Metadata Server APIs.

curl https://<YOUR-TECTON-CLUSTER>.tecton.ai/oauth2/default/v1/token -X POST \
-d "scope=everything&grant_type=client_credentials&client_id=$SA_ID&client_secret=$SA_SECRET"

You may also provide the Service Account ID and secret as a Basic authorization header instead, however we caution against this and recommend passing them in the request body as above.

curl https://<YOUR-TECTON-CLUSTER>.tecton.ai/oauth2/default/v1/token -X POST \
-d "scope=everything&grant_type=client_credentials" \
-H "Authorization: Basic $(echo -n "$SA_ID:$SA_SECRET" | base64)"

Example response:

{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"<SAVE-THIS-TOKEN>",
  "scope":"everything"
}

A newly granted access token has a lifetime of 1 hour before it expires. We recommend caching and reusing tokens, as well as a few other best practices.

caution

It can take up to one minute for the token issuing service to register changes to Service Accounts (e.g. activation/deactivation). Refer to best practices of caching and reusing access tokens.

Using the Access Token

Once you have an access token you may make requests to your Feature Service with a Bearer authorization header:

curl -X POST https://<YOUR-TECTON-CLUSTER>.tecton.ai/api/v2/workspaces/<YOUR-WORKSPACE>/feature-services/<FEATURE-SERVICE-NAME>/get-features\
-H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" -d '{
  "params": {
    "workspaceName": "<YOUR-WORKSPACE>",
    "featureServiceName": "<FEATURE-SERVICE-NAME>",
    "requestContextMap": {
      "amt": 101 # replace with your request body
    }
  }
}'

See Reading Feature Data for more information on calling feature server.

info

Please note that the Java and Python clients do not currently support calling Feature Services as OAuth Service Accounts.

OAuth Client Secret Rotation

Tecton provides support for rotating client secrets for OAuth Service Accounts programmatically. You may list, create, deactivate/reactivate, and delete client secrets provided that a Service Account has at least 1 active secret and no more than 2 client secrets total. A secret must also be deactivated before it is fully deleted.

You can rotate secrets as needed to meet your requirements, using the HTTP API or CLI.

Best Practices for OAuth

We recommend following these best practices for the reliability and security of your applications that use OAuth Service Accounts.

• Client secrets should be stored in a secure place such as a secret manager.
• Client secrets rotation should be automated on a schedule that meets your internal rotation policies.
• Access tokens should be cached by the application and reused for subsequent requests. They have a 1 hour lifespan.

HTTP API and Tecton CLI Reference

• HTTP API reference
• CLI reference

Troubleshooting

Common Issues

1. OAuth Token Request Failures

• Check network connectivity to Tecton instance
• Verify that the client ID and secret are correct, and that the client secret is active
• Verify that the Service Account is active

2. Authorization Failures to Feature Service

• If using OAuth, verify that the access token is not expired
• Verify the workspace and Feature Service names are correct
• Verify that the Service Account is active
• Verify that the Service Account has the correct roles on the Feature Service's workspace

OAuth Client Credentials Limitations

OAuth Client Credentials are subject to the following limitations:

• OAuth Service Accounts cannot be created from the Web UI.
• The Java and Python clients and CLI do not support authenticating as an OAuth Service Account.
• Ingest API and Metrics API do not accept OAuth access tokens.