# Set up the User Invitation API

This page explains how to set up the Cloud Identity User Invitation API.

## Enable the API and set up credentials

<br />

## Install the Python client library

To install the Python client library, run the following command:

```bash
  pip install --upgrade google-api-python-client google-auth \
    google-auth-oauthlib google-auth-httplib2
```

For more information about setting up your Python development environment, see
the [Python Development Environment Setup Guide](https://docs.cloud.google.com/python/docs/setup.md.txt).

## Authenticate and instantiate a client

To call the User Invitation API as a service account, you must use domain-wide
delegation (DWD). You can authenticate the service account using Application
Default Credentials (ADC) or a service account key.

To authenticate as an administrator without DWD, use end-user OAuth 2.0
credentials with the
`https://www.googleapis.com/auth/cloud-identity.userinvitations` scope instead.
For more information, see
[Using OAuth 2.0 for web server applications](https://developers.google.com/identity/protocols/oauth2/web-server#obtainingaccesstokens).

> [!WARNING]
> **Warning:** Domain-wide delegation (DWD) is a powerful privilege that lets a service account impersonate any user in your domain with the allowed scopes. Use DWD only when absolutely necessary, because it can pose a security risk. Whenever possible, grant specific Cloud Identity roles directly to the service account instead. The User Invitation API doesn't support granting a role to a service account, so service accounts require DWD. See [domain-wide delegation best practices](https://knowledge.workspace.google.com/admin/apps/domain-wide-delegation-best-practices).

### Set up domain-wide delegation

To use domain-wide delegation, you must grant the service account
authority to impersonate an administrator. Audit logs show any service account
actions as the impersonated user.

For instructions, see
[Delegate domain-wide authority to your service account](https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account).

To authorize the service account, provide the following scope:

- `https://www.googleapis.com/auth/cloud-identity.userinvitations`

### Instantiate a client

To instantiate a client, choose an authentication method. We recommend using
Application Default Credentials (ADC) if your code is running on
Google Cloud or using Workload Identity Federation.

### ADC

```python
from google.auth import iam
from google.auth.transport import requests
import google.auth
from google.oauth2 import service_account

INITIAL_SCOPES = ['https://www.googleapis.com/auth/iam']
CI_SCOPES = ['https://www.googleapis.com/auth/cloud-identity.userinvitations']
TOKEN_URI = "https://accounts.google.com/o/oauth2/token"

def create_delegated_credentials(
  user_email: str
) -> google.auth.credentials.Credentials:
  """Creates delegated credentials for the user.

  Args:
    user_email: The administrator email to call as.

  Returns:
    The delegated credentials for the user.
  """

  # Fetch application default credentials (ADC)
  credentials, _ = google.auth.default(scopes=INITIAL_SCOPES)

  # Populate account information
  request = requests.Request()
  credentials.refresh(request)

  # Create an IAM signer
  signer = iam.Signer(request, credentials,
                      credentials.service_account_email)

  # Create domain-wide delegated (DWD) credentials
  delegated_credentials = service_account.Credentials(
      signer=signer,
      service_account_email=credentials.service_account_email,
      token_uri=TOKEN_URI,
      scopes=CI_SCOPES,
      subject=user_email
  )

  return delegated_credentials
```

### Service account key

```python
from google.oauth2 import service_account
import googleapiclient.discovery

SCOPES = ['https://www.googleapis.com/auth/cloud-identity.userinvitations']
SERVICE_ACCOUNT_FILE = '/path/to/service-account-file.json'

def create_service():
  credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)
  delegated_credentials = credentials.with_subject('user@altostrat.com')

  service_name = 'cloudidentity'
  api_version = 'v1'
  service = googleapiclient.discovery.build(
    service_name,
    api_version,
    credentials=delegated_credentials)

  return service
```

After running this code, you can begin making calls to the User Invitation API.

## What's next

- [Create and manage user invitations](https://docs.cloud.google.com/identity/docs/how-to/manage-user-invitations.md.txt)