Migrating to the Directory API

Developers using the Provisioning or Profiles APIs who need to update their apps to use the Directory API can use this guide as a reference for their migration.

The Directory API is built on Google's JSON-based API infrastructure, which is not backward compatible with the XML-based Provisioning and Profiles APIs.

For more information about the resources available in the Directory API, see the API Reference.

Authorizing requests

All authorized requests must now use the OAuth 2.0 protocol. The authorization scopes accepted by the Profiles and Provisioning APIs have been replaced by several new scopes. Scopes supported by the Profiles and Provisioning APIs are also supported by the Directory API, but new applications should use the existing Directory API scopes.

The following tables map the currently supported scopes to their Directory API equivalents:

Profiles API Directory API
https://www.google.com/m8/feeds/profiles https://www.googleapis.com/auth/admin.directory.user
Provisioning API Directory API
https://apps-apis.google.com/a/feeds/groups/ https://www.googleapis.com/auth/admin.directory.group
https://apps-apis.google.com/a/feeds/alias/ https://www.googleapis.com/auth/admin.directory.user
https://apps-apis.google.com/a/feeds/policies/ https://www.googleapis.com/auth/admin.directory.orgunit
https://apps-apis.google.com/a/feeds/user/ https://www.googleapis.com/auth/admin.directory.user

Migrate from the Profiles API v3

The Directory API provides similar functionality to the Profiles API for managing profile information for G Suite domain users. Unlike the Profiles API, which maintained profile information separately from account information exposed through the Provisioning API, the Directory API includes a user's profile information with their account in the Users resource. User profile photos are now stored in the Users.photos resource.

Migrate from the Provisioning API v2

The Directory API provides similar functionality to the Provisioning API for managing user accounts, groups, and organizational units, as well as several new features. This guide maps features between the APIs and highlights any notable differences.

The following table maps high-level Provisioning API features to their Directory API equivalent:

Provisioning API Directory API
User accounts Users resource
Nicknames Users.aliases
User aliases in multiple domains
Groups Groups resource
Group members Members resource
Group owners Group ownership is determined by the Members.role property
Organizational units Orgunits
Organization users Organization membership is now determined by the Users.orgUnitPath property when creating or updating a user

Request syntax

The Provisioning API requires an account domain as part of the request URL for most operations. The Directory API doesn't not require this and instead uses unique identifiers for resources such as users and groups.

User accounts and multi-domain users

The User feed exposed by the Provisining API to manage user accounts has been replaced by the Users resource in the Directory API. For information on performing common user management tasks with the Directory API, see the Developer's Guide.

The Provisioning API supports multi-domain users by including the domain name in the request URL. In contrast, the Directory API stores the account's primary domain name in the primaryEmail property of the Users resource. Domain users are now referred to by their userKey in the API request. For an example of how this works in the Directory API, see Retrieve all account users.

The following table maps the endpoints for the User feed in the Provisioning API with those for the Users resource in the Directory API:

Provisioning API Directory API
https://apps-apis.google.com/a/feeds/domain/user/2.0 https://www.googleapis.com/admin/directory/v1/users
https://apps-apis.google.com/a/feeds/domain/user/2.0/userName https://www.googleapis.com/admin/directory/v1/users/userKey
Admin status is changed when creating or updating a user https://www.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

Nicknames and aliases

The Directory API has replaced the Provisioning API's Nicknames feed for managing single domain account nicknames and the User Alias feed for managing multiple domain account aliases with the Users.alias resource.

The Directory API user alias supports both single and multiple domain accounts. A user alias is now simply an alternate email address that uses the same mailbox used by the user's primary email address. A user's alias can be associated with a different account domain than the domain used by the user's primary email address for accounts with multiple domains.

The following table maps the endpoints for the Nicknames feed and the User Aliases feed in the Provisioning API with those for the Users.alias resource in the Directory API:

Provisioning API Directory API
https://apps-apis.google.com/a/feeds/domain/nickname/2.0 https://www.googleapis.com/admin/directory/v1/users/userKey/aliases
https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname https://www.googleapis.com/admin/directory/v1/users/userKey/aliases/alias
https://apps-apis.google.com/a/feeds/alias/2.0/domain https://www.googleapis.com/admin/directory/v1/users/userKey/aliases
https://apps-apis.google.com/a/feeds/alias/2.0/domain/email https://www.googleapis.com/admin/directory/v1/users/userKey/aliases/alias

Groups

The Groups feed exposed by the Provisioning API to manage groups has been replaced by the Groups resource. For information on performing common group management tasks with the Directory API, see the Developer's Guide.

The following table maps the endpoints for the Groups feed in the Provisioning API with those for the Groups resource in the Directory API:

Provisioning API Directory API
https://apps-apis.google.com/a/feeds/group/2.0/domain https://www.googleapis.com/admin/directory/v1/groups
https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId https://www.googleapis.com/admin/directory/v1/groups/groupKey

Group members and group ownership

The Group Members feed exposed by the Provisioning API to manage group memberships has been replaced by the Members resource in the Directory API.

The Group Owners feed has no direct replacement in the Directory API. Instead, group ownership is now set through the role property of the Members resource.

For more information on performing common group member and ownership management tasks with the Directory API, see the Developer's Guide.

The following table maps the endpoints for the Group Members feed in the Provisioning API with those for the Members resource in the Directory API:

Provisioning API Directory API
https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member https://www.googleapis.com/admin/directory/v1/groups/groupKey/members
https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member/memberId https://www.googleapis.com/admin/directory/v1/groups/groupKey/members/memberKey

Organizational units

The Organizational Units feed exposed by the Provisioning API to manage organizational units has been replaced by the Orgunits resource. For more information on performing common organizational unit tasks with the Directory API, see the Developer's Guide.

The account's customer ID is now returned in the customerId property of the Users resource in the Directory API. As an administrator, you can also use the my_customer alias for the customer ID.

The following table maps the endpoints for the Organizational Units endpoints in the Provisioning API with those for the Orgunits resource in the Directory API:

Provisioning API Directory API
https://apps-apis.google.com/a/feeds/customer/2.0/customerId As an account administrator, you can use the my_customer alias to represent your account's customerId. The customerId is also returned as part of the Users resource.
https://apps-apis.google.com/a/feeds/orgunit/2.0/the customerId https://www.googleapis.com/admin/directory/v1/customer/customerId/orgunits
https://apps-apis.google.com/a/feeds/orgunit/2.0/the customerId/full org unit path https://www.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath*

Organization users

The Organization Users feed in the Provisioning API has no direct replacement in the Directory API. The Users resource now contains the user's parent organizational unit in the orgUnitPath field.

New features

The Directory API contains several new features that were not supported by the Provisioning API. Some of the new features include:

Send feedback about...

Directory API
Directory API
Need help? Visit our support page.