Getting Started with the API

The UTA Authoritative Data API is a GraphQL API that lets you read and write party data — clients, talent, contacts, venues, and more — in a structured and governed way.

This guide introduces the concepts you'll need before making your first API call.

---

Domains

INFO

We maintain two environments: Development and Production. These environments have separate Neo4j Databases and separate API versions. The Development Auth Data API contains all of the latest features that the team produces, and is available for testing ahead of promotion to Production. The Development space is generally considered a shared testing ground, and the data is not in a particularly clean state given this fact. Once functionality is evaluated in Development, it's promoted to the Production API, which is what is powering the Production versions of other Apps.

---

Authentication

The API supports two authentication models depending on your use case.

User Auth

INFO

Our Authentication and Authorization are based around Entra users. TODO: need further details on this, but in general all of our FE apps use the same Entra Auth brokered access flows, so please go check those out. Requires: Entra App Registration Entra APIM Subscription Key

Service Auth

TODO

Service Auth is intended for direct service integrations with the Auth Data APIs. This is accomplished using signed JWTs.

1. Get a Subscription Key (request from API team)
2. Get a custom Named Value (your JWT secret, request from API team)
3. Generate 1 hour JWT and send via basic auth.

Example Python Snippet:

import datetime
import jwt

def generate_jwt():
    now = datetime.datetime.now(datetime.timezone.utc)
    payload = {
        "exp": now + datetime.timedelta(hours=1),  # Expiration time
        "iat": now,  # Issued at time
        "upn": "an.email.which.identifies.your.service@unitedtalent.com",
    }

    # Encoding the JWT
    encoded_jwt = jwt.encode(payload, SECRET_KEY, algorithm="HS256")

    return encoded_jwt

---

Making Your First Request

Once you have credentials and an endpoint URL, you can query the API using any GraphQL client (e.g., Apollo, Postman, or a plain HTTP client).

All requests go to a single GraphQL endpoint:

POST <YOUR_API_ENDPOINT>/graphql

Include your auth token in the Authorization header:

Authorization: Bearer <your-token>

Example: Fetch All Rep Areas

A simple read query to verify your setup is working:

query {
  getAllRepAreas {
    items {
      id
      name
    }
  }
}

---

Next Steps

Once you're authenticated, see the individual mutation guides to start creating records:

• Create a Client
• Create Talent
• Create a Contact