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
Description Search for organizations that match the conditions specified in the request. Non-admin users will only match organizations that they have rights on.
Request type SearchOrganizationsRequest
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 id
Type string
Description

Immutable and unique public identifier for the API key. Generated by the Access Server.
Field key
Type string
Description

Immutable and unique secret value of the API key. Generated by the Access Server.
Field name
Type string
Description

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

max_len: 50
Field rights
Type repeated Right
Description

Rights that are granted to this API key.

defined_only
Field created_at
Type google.protobuf.Timestamp
Field updated_at
Type google.protobuf.Timestamp
Show object example 
{
  "id": "",
  "key": "",
  "name": "",
  "rights": [],
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
}

Message APIKeys

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

Message Collaborator

Field ids
Type OrganizationOrUserIdentifiers
Description

required
Field rights
Type repeated Right
Description

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

Message Collaborators

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

Message CreateOrganizationAPIKeyRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field name
Type string
Description

max_len: 50
Field rights
Type repeated Right
Description

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

Message CreateOrganizationRequest

Field organization
Type Organization
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

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 ids
Type OrganizationOrUserIdentifiers
Field rights
Type repeated Right
Description
Show object example 
{
  "ids": {},
  "rights": [],
}

Message GetOrganizationAPIKeyRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field key_id
Type string
Description

Unique public identifier for the API key.
Show object example 
{
  "organization_ids": {},
  "key_id": "",
}

Message GetOrganizationCollaboratorRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

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

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

Message GetOrganizationRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field field_mask
Type google.protobuf.FieldMask
Description

The names of the organization fields that should be returned.
Show object example 
{
  "organization_ids": {},
  "field_mask": {},
}

Message ListOrganizationAPIKeysRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000
Field page
Type uint32
Description

Page number for pagination. 0 is interpreted as 1.
Show object example 
{
  "organization_ids": {},
  "limit": 0,
  "page": 0,
}

Message ListOrganizationCollaboratorsRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000
Field page
Type uint32
Description

Page number for pagination. 0 is interpreted as 1.
Show object example 
{
  "organization_ids": {},
  "limit": 0,
  "page": 0,
}

Message ListOrganizationsRequest

Field collaborator
Type OrganizationOrUserIdentifiers
Description

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 field_mask
Type google.protobuf.FieldMask
Description

The names of the organization fields that should be returned.
Field order
Type string
Description

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]
Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000
Field page
Type uint32
Description

Page number for pagination. 0 is interpreted as 1.
Field deleted
Type bool
Description

Only return recently deleted organizations.
Show object example 
{
  "collaborator": {},
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
  "deleted": false,
}

Message Organization

Field ids
Type OrganizationIdentifiers
Description

required
Field created_at
Type google.protobuf.Timestamp
Field updated_at
Type google.protobuf.Timestamp
Field deleted_at
Type google.protobuf.Timestamp
Field name
Type string
Description

max_len: 50
Field description
Type string
Description

max_len: 2000
Field attributes
Type map of string to string
Description

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

max_pairs: 10

max_len (key): 36

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

max_len (value): 200
Field contact_info
Type repeated ContactInfo
Description

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

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

Message OrganizationIdentifiers

Field organization_id
Type string
Description

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 organization_ids
Type OrganizationIdentifiers
Field user_ids
Type UserIdentifiers
Restrictions
Only one of organization_ids, user_ids can be set.
Show object example 
{
  "organization_ids": {},
  "user_ids": {},
}

Message Organizations

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

Message Rights

Field rights
Type repeated Right
Description

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

Message SearchOrganizationsRequest

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

Field id_contains
Type string
Description

Find organizations where the ID contains this substring.

max_len: 50
Field name_contains
Type string
Description

Find organizations where the name contains this substring.

max_len: 50
Field description_contains
Type string
Description

Find organizations where the description contains this substring.

max_len: 50
Field attributes_contain
Type map of string to string
Description

Find organizations where the given attributes contain these substrings.

max_pairs: 10

max_len (key): 36

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

max_len (value): 50
Field field_mask
Type google.protobuf.FieldMask
Field order
Type string
Description

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.
Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000
Field page
Type uint32
Description

Page number for pagination. 0 is interpreted as 1.
Field deleted
Type bool
Description

Only return recently deleted organizations.
Show object example 
{
  "id_contains": "",
  "name_contains": "",
  "description_contains": "",
  "attributes_contain": {},
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
  "deleted": false,
}

Message SetOrganizationCollaboratorRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field collaborator
Type Collaborator
Description

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

Message UpdateOrganizationAPIKeyRequest

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field api_key
Type APIKey
Description

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

Message UpdateOrganizationRequest

Field organization
Type Organization
Description

required
Field field_mask
Type google.protobuf.FieldMask
Description

The names of the organization fields that should be updated.
Show object example 
{
  "organization": {},
  "field_mask": {},
}

Message UserIdentifiers

Field user_id
Type string
Description

This ID shares namespace with organization IDs.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field email
Type string
Description

Secondary identifier, which can only be used in specific requests.
Show object example 
{
  "user_id": "",
  "email": "",
}
← Network Server APIs Storage Integration API →