Quick Start with APIs

This document outlines the steps required to gain access to the Enterprise API, including port forwarding, adding a new client, and obtaining an access token.

Quick Start

1. Authentication: Make a call to get either an access (bearer) token or a refresh token.
2. API Calls: Use the token from step 1 to initiate your API calls.

To make this easy, we've provided a library of queries and mutations within this portal. Here's what you need to do:

1. Find the query you want to run in the documentation.
2. Configure it using your Client ID and the bearer/refresh token (you'll get this from the authentication call).
3. Start making your API calls. You can use the code editor tabs to generate code snippets in many languages once you've made your API calls.

APIs

We use GraphQL for our Search and Management APIs, so you can customize how much data you get with each call. We use REST for our Ingestion API, so you can upload, modify, and delete content using the Ingestion API. You can find our Swagger documentation here.

Base URLs for Private Cloud Clients:

https://{YOUR-DOMAIN}/auth                                  # Authentication Endpoint
https://{YOUR-DOMAIN}/services/i/graphql-gateway-external   # GraphQL Endpoint
https://{YOUR-DOMAIN}/services/i/ingestion-api/v1/...       # Ingestion Endpoint

Creating API Credentials

Port Forwarding

First, establish a port forwarding session to the auth-ws service in the platform namespace:

kubectl -n platform port-forward svc/auth-ws 8080:80

Adding a New Client

To add a new client, execute the following CURL command. Replace CLIENT_NAME with your desired client name and RANDOM_CLIENT_SECRET with a randomly generated string of 48 characters:

curl --location --request POST 'http://localhost:8080/internal/client/add' \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": ["read"],
    "client_id": "as-api-{CLIENT_NAME}",
    "client_secret": "{RANDOM_CLIENT_SECRET}",
    "authorized_grant_types": ["password", "refresh_token", "access_token"],
    "access_token_validity": 2592000,
    "refresh_token_validity": 31622400
}'

Confirming Client Addition

To confirm that the client was added successfully, use the following CURL command. Replace CLIENT_ID with the actual client ID:

curl --location --request GET 'http://localhost:8080/internal/client/as-api-{CLIENT_ID}'

Obtaining an Access Token

Calling the Auth Endpoint

To call the auth API with the correct client credentials and obtain an access token, use the following CURL command. This token needs to be refreshed every 24 hours:

Password Authentication

curl --location --request POST 'https://{CLIENT_DOMAIN}/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={USERNAME}' \
--data-urlencode 'password={PASSWORD}' \
--data-urlencode 'client_id=as-api-{CLIENT_NAME}' \
--data-urlencode 'client_secret={CLIENT_SECRET}'

Ensure to replace placeholders like USERNAME, PASSWORD, CLIENT_NAME, and CLIENT_SECRET with the actual values.

SSO Authentication

kubectl -n platform port-forward svc/auth-ws 8080:80
curl --location --request POST 'http://localhost:8080/internal/token/create?username={{username}}&clientId={{generated-id}}'