Organization APIs

The OrganizationRegistry service

Method OrganizationRegistry.Create
Description Create a new organization. This also sets the given user as first collaborator with all possible rights.
Request type CreateOrganizationRequest
Response type Organization
HTTP bindings

POST /api/v3/users/{collaborator.user_ids.user_id}/organizations

Method OrganizationRegistry.Get
Description Get the organization with the given identifiers, selecting the fields specified in the field mask. More or less fields may be returned, depending on the rights of the caller.
Request type GetOrganizationRequest
Response type Organization
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}

Method OrganizationRegistry.List
Description List organizations where the given user or organization is a direct collaborator. If no user or organization is given, this returns the organizations the caller has access to. Similar to Get, this selects the fields given by the field mask. More or less fields may be returned, depending on the rights of the caller.
Request type ListOrganizationsRequest
Response type Organizations
HTTP bindings

GET /api/v3/organizations

GET /api/v3/users/{collaborator.user_ids.user_id}/organizations

Method OrganizationRegistry.Update
Description Update the organization, changing the fields specified by the field mask to the provided values.
Request type UpdateOrganizationRequest
Response type Organization
HTTP bindings

PUT /api/v3/organizations/{organization.ids.organization_id}

Method OrganizationRegistry.Delete
Description Delete the organization. This may not release the organization ID for reuse.
Request type OrganizationIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/organizations/{organization_id}

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchOrganizations
Request type SearchEntitiesRequest
Response type Organizations
HTTP bindings

GET /api/v3/search/organizations

The OrganizationAccess service

Method OrganizationAccess.ListRights
Description List the rights the caller has on this organization.
Request type OrganizationIdentifiers
Response type Rights
HTTP bindings

GET /api/v3/organizations/{organization_id}/rights

Method OrganizationAccess.CreateAPIKey
Description Create an API key scoped to this organization. Organization API keys can give access to the organization itself, as well as any application, gateway and OAuth client this organization is a collaborator of.
Request type CreateOrganizationAPIKeyRequest
Response type APIKey
HTTP bindings

POST /api/v3/organizations/{organization_ids.organization_id}/api-keys

Method OrganizationAccess.ListAPIKeys
Description List the API keys for this organization.
Request type ListOrganizationAPIKeysRequest
Response type APIKeys
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}/api-keys

Method OrganizationAccess.GetAPIKey
Description Get a single API key of this organization.
Request type GetOrganizationAPIKeyRequest
Response type APIKey
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}/api-keys/{key_id}

Method OrganizationAccess.UpdateAPIKey
Description Update the rights of an API key of the organization. This method can also be used to delete the API key, by giving it no rights. The caller is required to have all assigned or/and removed rights.
Request type UpdateOrganizationAPIKeyRequest
Response type APIKey
HTTP bindings

PUT /api/v3/organizations/{organization_ids.organization_id}/api-keys/{api_key.id}

Method OrganizationAccess.GetCollaborator
Description Get the rights of a collaborator (member) of the organization. Pseudo-rights in the response (such as the “_ALL” right) are not expanded.
Request type GetOrganizationCollaboratorRequest
Response type GetCollaboratorResponse
HTTP bindings

/api/v3

GET /api/v3/organizations/{organization_ids.organization_id}/collaborator/user/{collaborator.user_ids.user_id}

Method OrganizationAccess.SetCollaborator
Description Set the rights of a collaborator (member) on the organization. Organization collaborators can get access to the organization itself, as well as any application, gateway and OAuth client this organization is a collaborator of. This method can also be used to delete the collaborator, by giving them no rights. The caller is required to have all assigned or/and removed rights.
Request type SetOrganizationCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

PUT /api/v3/organizations/{organization_ids.organization_id}/collaborators

Method OrganizationAccess.ListCollaborators
Description List the collaborators on this organization.
Request type ListOrganizationCollaboratorsRequest
Response type Collaborators
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}/collaborators

Messages

Message APIKey

Field Type Description
id string

Immutable and unique public identifier for the API key. Generated by the Access Server.

key string

Immutable and unique secret value of the API key. Generated by the Access Server.

name string

User-defined (friendly) name for the API key.

max_len: 50

rights repeated Right

Rights that are granted to this API key.

defined_only

Show object example
{
  "id": "",
  "key": "",
  "name": "",
  "rights": [],
}

Message APIKeys

Field Type Description
api_keys repeated APIKey
Show object example
{
  "api_keys": [],
}

Message Collaborator

Field Type Description
ids OrganizationOrUserIdentifiers

required

rights repeated Right

defined_only

Show object example
{
  "ids": {},
  "rights": [],
}

Message Collaborators

Field Type Description
collaborators repeated Collaborator
Show object example
{
  "collaborators": [],
}

Message CreateOrganizationAPIKeyRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

name string

max_len: 50

rights repeated Right

defined_only

Show object example
{
  "organization_ids": {},
  "name": "",
  "rights": [],
}

Message CreateOrganizationRequest

Field Type Description
organization Organization

required

collaborator OrganizationOrUserIdentifiers

Collaborator to grant all rights on the newly created application. NOTE: It is currently not possible to have organizations collaborating on other organizations.

required

Show object example
{
  "organization": {},
  "collaborator": {},
}

Message GetCollaboratorResponse

Field Type Description
ids OrganizationOrUserIdentifiers
rights repeated Right
Show object example
{
  "ids": {},
  "rights": [],
}

Message GetOrganizationAPIKeyRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

key_id string

Unique public identifier for the API key.

Show object example
{
  "organization_ids": {},
  "key_id": "",
}

Message GetOrganizationCollaboratorRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

collaborator OrganizationOrUserIdentifiers

NOTE: It is currently not possible to have organizations collaborating on other organizations.

required

Show object example
{
  "organization_ids": {},
  "collaborator": {},
}

Message GetOrganizationRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

field_mask google.protobuf.FieldMask

The names of the organization fields that should be returned.

Show object example
{
  "organization_ids": {},
  "field_mask": {},
}

Message ListOrganizationAPIKeysRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

Show object example
{
  "organization_ids": {},
  "limit": 0,
  "page": 0,
}

Message ListOrganizationCollaboratorsRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

Show object example
{
  "organization_ids": {},
  "limit": 0,
  "page": 0,
}

Message ListOrganizationsRequest

Field Type Description
collaborator OrganizationOrUserIdentifiers

By default we list all organizations the caller has rights on. Set the user to instead list the organizations where the user or organization is collaborator on. NOTE: It is currently not possible to have organizations collaborating on other organizations.

field_mask google.protobuf.FieldMask

The names of the organization fields that should be returned.

order string

Order the results by this field path (must be present in the field mask). Default ordering is by ID. Prepend with a minus (-) to reverse the order.

in: [ organization_id -organization_id name -name created_at -created_at]

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

Show object example
{
  "collaborator": {},
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
}

Message Organization

Field Type Description
ids OrganizationIdentifiers

required

created_at google.protobuf.Timestamp
updated_at google.protobuf.Timestamp
name string

max_len: 50

description string

max_len: 2000

attributes map of string to string

Key-value attributes for this organization. Typically used for organizing organizations or for storing integration-specific data.

contact_info repeated ContactInfo

Contact information for this organization. Typically used to indicate who to contact with security/billing questions about the organization.

Show object example
{
  "ids": {},
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "name": "",
  "description": "",
  "attributes": {},
  "contact_info": [],
}

Message OrganizationIdentifiers

Field Type Description
organization_id string

This ID shares namespace with user IDs.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

Show object example
{
  "organization_id": "",
}

Message OrganizationOrUserIdentifiers

OrganizationOrUserIdentifiers contains either organization or user identifiers.

Field Type Description
organization_ids OrganizationIdentifiers
user_ids UserIdentifiers
Restrictions
Only one of organization_ids, user_ids can be set.
Show object example
{
  "organization_ids": {},
  "user_ids": {},
}

Message Organizations

Field Type Description
organizations repeated Organization
Show object example
{
  "organizations": [],
}

Message Rights

Field Type Description
rights repeated Right

defined_only

Show object example
{
  "rights": [],
}

Message SearchEntitiesRequest

This message is used for finding entities in the EntityRegistrySearch service.

Field Type Description
id_contains string

Find entities where the ID contains this substring.

name_contains string

Find entities where the name contains this substring.

description_contains string

Find entities where the description contains this substring.

attributes_contain map of string to string

Find entities where the given attributes contain these substrings.

field_mask google.protobuf.FieldMask
order string

Order the results by this field path (must be present in the field mask). Default ordering is by ID. Prepend with a minus (-) to reverse the order.

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

Show object example
{
  "id_contains": "",
  "name_contains": "",
  "description_contains": "",
  "attributes_contain": {},
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
}

Message SetOrganizationCollaboratorRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

collaborator Collaborator

required

Show object example
{
  "organization_ids": {},
  "collaborator": {},
}

Message UpdateOrganizationAPIKeyRequest

Field Type Description
organization_ids OrganizationIdentifiers

required

api_key APIKey

required

Show object example
{
  "organization_ids": {},
  "api_key": {},
}

Message UpdateOrganizationRequest

Field Type Description
organization Organization

required

field_mask google.protobuf.FieldMask

The names of the organization fields that should be updated.

Show object example
{
  "organization": {},
  "field_mask": {},
}

Message UserIdentifiers

Field Type Description
user_id string

This ID shares namespace with organization IDs.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

email string

Secondary identifier, which can only be used in specific requests.

Show object example
{
  "user_id": "",
  "email": "",
}