---
title: Provider authorization and domain grants
description: Understand how provider credentials, account context, host owners, domain grants, reusable connections, continuations, and revocation fit together.
sidebar:
  label: Connections and grants
seo:
  title: Provider authorization and domain grants in DomainKit
---

Connecting a DNS provider crosses two authority systems: the provider's account and scopes, and the
host application's users, tenants, and domains. DomainKit keeps those systems explicit instead of
equating one provider token with one product domain.

## The authorization aggregate

A durable provider authorization contains:

- the provider and account identity;
- non-secret provider context needed to reconstruct the correct client;
- a reference to the host-stored credential;
- required capabilities and their evidence;
- expiry and revocation state;
- one or more host-owner bindings and grants.

The credential is part of one logical aggregate, but DomainKit does not choose how the host encrypts
or persists it.

## Owner bindings and grants

A provider authorization can be bound to a host owner with:

- an account-wide grant, optionally excluding domains; or
- an explicit set of domain grants.

The grant is enforced in addition to provider scopes. A broad Cloudflare or Vercel credential does
not automatically authorize every host tenant or every visible zone.

This separation allows one valid provider authorization to serve another domain for the same owner
without repeating provider consent.

## Starting and completing a connection

`Connection.start` accepts a token method or an interactive provider flow:

```text
token
  -> validate provider authority
  -> commit authorization aggregate

interactive
  -> create one-time continuation
  -> redirect to provider
  -> consume callback continuation
  -> exchange code
  -> commit authorization aggregate
```

Cloudflare implements standards-based OAuth and scoped API tokens. Vercel implements its
provider-specific Integration installation flow and tokens. DomainKit does not label every
redirect/code exchange as generic OAuth.

## Reusing provider authority

`Connection.extend` adds a new domain grant only after the host:

1. loads an authorization owned by the same host owner;
2. proves the provider authorization can serve the requested domain;
3. obtains the owner's consent for the new grant.

Reuse preserves earlier grants. It rejects cross-owner, expired, insufficient, or revoking
authorizations.

## Removing a domain

Removing one domain binding preserves the other bindings and normally preserves DNS. If the removed
binding was the last one, the authorization lifecycle attempts provider revocation before deleting
the durable authorization and credential state.

Revocation is fail-closed. Durable retry state remains until the provider confirms the outcome.

## Host-owned boundaries

The host supplies:

- authenticated start, callback, token, reuse, and disconnect routes;
- user and tenant authorization policy;
- one durable `AuthorizationLifecycle.Repository`;
- credential encryption or vault storage;
- a short-lived, one-time continuation store;
- consent records and audit history.

A SQL application can implement the aggregate commit as one transaction. A split database/vault
application must implement a recoverable saga behind the same repository boundary.

## Capability evidence

Provider scope strings are not treated as complete proof. Required capabilities record one of three
evidence levels:

- `Declared` — the host or provider flow claims the capability;
- `Introspected` — a provider response reported it;
- `Exercised` — a successful provider operation demonstrated it.

The host can promote evidence after successful use without changing the underlying grant model.

## Put the concept to work

- [Integrate a host application](/docs/guides/host-integration)
- [Connect Cloudflare](/docs/providers/cloudflare)
- [Connect Vercel](/docs/providers/vercel)
- [Authorization API reference](/docs/reference/core#authorization-and-connections)