Set Up GraphOS Agent Services

To complete this tutorial, you need an Org Admin role. You create a sandbox organization, connect a service, define tags, and write the first access rule.

After completing these steps, start the local runtime and confirm enforcement.

Prerequisites

Your Apollo contact provides the onboarding kit.

Confirm your organization and graph

You need a new, temporary GraphOS organization, not your company's existing Apollo org. Ask your Apollo contact whether your contact has already created the organization.

Treat this organization as a sandbox. Graphs, policy, and connectors you set up here don't carry over to a permanent organization.

If you create the organization yourself:

1. Sign out of your usual Apollo account. Clear cookies for apollographql.com and auth.apollographql.com, or use a fresh incognito window.

2. Sign in with GitHub or a username and password. This sandbox org doesn't support single sign-on (SSO). You can reuse your work email, but pair it with a new password or your GitHub identity, not company SSO.

3. Create the organization. The person who creates the organization is the Org Admin for that organization and invites any teammates who need access.

4. Let your Apollo contact know that the organization has been created and the ID of the organization. Your contact needs to enable GraphOS Agent Services for the organization.

Then, create a GraphOS Agent Services graph.

1. Navigate to GraphOS Agent Services at https://constellation.apollographql.com.

2. Select Set up GraphOS graph and give the graph a title.

Unzip the onboarding kit

1. Unzip the kit your Apollo contact sent into a new directory. Don't unzip over an older kit.

2. In a terminal, go to that directory.

The kit is self-contained. The only value you fill in by hand is your personal API key.

Add your personal API key

1. Copy the example environment file:

   terminal

   copy

   cp .env.example .env

2. In Studio, select your avatar on the top right, then Personal settings → API Keys.

3. Create a new personal API key. This key starts with user:.

4. Set APOLLO_POLICY_KEY in .env to that value.

If the service you connect uses a credential (GITHUB_TOKEN, SLACK_TOKEN, and similar), set that value in .env too. Leave unused connector credentials as REPLACE_ME.

Connect your first service

Connect a catalog service before anyone starts the runtime. This tutorial uses The Cat API as the demo service. Your Apollo contact might name a different service; the wizard steps stay the same. For more information on every field in the wizard, go to Connect Services.

1. In GraphOS Agent Services, open Services and click Add service.

2. Select The Cat API, or the connector your Apollo contact names.

3. On Configure, keep the default name and base URL unless your Apollo contact gives you different values. If the connector needs a credential, set the environment variable name to match .env.

4. On Tags, review the tags the catalog already applied. You need at least one tag that you can allow and one that you can deny.

5. On Rules, accept the defaults. You write the session's first rule in YAML in the next step, and that file is authoritative.

6. On Review, confirm and finish.

Stay on this step until the service shows as connected.

Write your first access rule

Open 01-policy/policy_rules.yaml in the kit. This file is the source of truth for graph-wide classification rules. When you apply it, GraphOS Agent Services deletes any in-scope rule that isn't listed here.

Keep two kinds of rule for the demo: one open classification and one denied classification the agent can request.

1deny_reason: "Field requires explicit access request via the Access Request workflow."
2services:
3  - service_id: REPLACE_ME
4    rules:
5      - {
6          classification: sensitivity-low,
7          effect: ALLOW,
8          title: "Low sensitivity: open",
9        }
10      - {
11          classification: can-see-images,
12          effect: DENY,
13          deny_visibility: REQUESTABLE,
14          title: "Images: request access",
15        }
16      - {
17          classification: can-see-description,
18          effect: DENY,
19          deny_visibility: REQUESTABLE,
20          title: "Description: request access",
21        }

If your service doesn't use can-see-images and can-see-description, replace those classifications with the tags you saw on Tags. The kit fills in service_id from your graph the first time you apply policy. Don't edit service_id unless the value is wrong.

For more rule shapes, go to Access Rules YAML Reference.

Copy 01-policy/policy_rules.yaml into the kit your teammates use. Teammates apply the file when starting the local runtime.