Skip to content
Cloud
Docs

IAM API reference

Project IAM policies, identities, and credentials.

Published contracts: @socra/iam-api@0.2.1.

Base URL

https://iam.socra.cloud

Service authorization definitions

A producer-owned catalog of project permissions and predefined roles.

Get service authorization definition

GET/admin/v1/service-authorizations/{service}

Path parameters

servicestringrequired
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

Query parameters

No query parameters

Response

6 fields

servicestringrequired
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
permission_prefixstringrequired
pattern: ^[a-z][a-z0-9]*$
role_prefixstringrequired
pattern: ^[a-z][a-zA-Z0-9._-]*$
permissionsobject[]required
namestringrequired
min length: 3 · max length: 256 · pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nullrequired
default: null
basic_roles"owner" | "editor" | "viewer"[]required
default: []
rolesobject[]required
namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nullrequired
default: null
permissionsstring[]required
min items: 1
updated_atcustomrequired

Synchronize service authorization definition

PATCH/admin/v1/service-authorizations/{service}

Path parameters

servicestringrequired
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

Request body

permission_prefixstringrequired
pattern: ^[a-z][a-z0-9]*$
role_prefixstringrequired
pattern: ^[a-z][a-zA-Z0-9._-]*$
permissionsobject[]required
namestringrequired
min length: 3 · max length: 256 · pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nulloptional
default: null
basic_roles"owner" | "editor" | "viewer"[]optional
default: []
rolesobject[]required
namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nulloptional
default: null
permissionsstring[]required
min items: 1

Response

6 fields

servicestringrequired
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
permission_prefixstringrequired
pattern: ^[a-z][a-z0-9]*$
role_prefixstringrequired
pattern: ^[a-z][a-zA-Z0-9._-]*$
permissionsobject[]required
namestringrequired
min length: 3 · max length: 256 · pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nullrequired
default: null
basic_roles"owner" | "editor" | "viewer"[]required
default: []
rolesobject[]required
namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nullrequired
default: null
permissionsstring[]required
min items: 1
updated_atcustomrequired

IAM permissions

Discoverable project permissions declared by Socra services.

List IAM permissions

GET/v1/permissions

Query parameters

servicestringoptional
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

Response

2 fields

dataobject[]required
namestringrequired
min length: 3 · max length: 256 · pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nullrequired
default: null
basic_roles"owner" | "editor" | "viewer"[]required
default: []
servicestringrequired
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
has_morefalserequired

IAM predefined roles

Discoverable predefined roles assignable in project IAM policies.

List IAM predefined roles

GET/v1/roles

Query parameters

servicestringoptional
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

Response

2 fields

dataobject[]required
namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
titlestringrequired
min length: 1 · max length: 256
descriptionstring | nullrequired
default: null
permissionsstring[]required
min items: 1
servicestringrequired
min length: 1 · max length: 253 · pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
has_morefalserequired

IAM custom roles

A project-owned role composed from service-declared permissions.

Create custom role

POST/v1/projects/{project_id}/roles

Path parameters

project_idcustomrequired

Request body

role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nullrequired
permissionsstring[]required
min items: 1 · max items: 100
stage"alpha" | "beta" | "ga" | "disabled"required

Response

9 fields

namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
project_idcustomrequired
role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nullrequired
permissionsstring[]required
min items: 1 · max items: 100
stage"alpha" | "beta" | "ga" | "disabled"required
created_atcustomrequired
updated_atcustomrequired

List custom roles

GET/v1/projects/{project_id}/roles

Path parameters

project_idcustomrequired

Query parameters

Response

2 fields

dataobject[]required
namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
project_idcustomrequired
role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nullrequired
permissionsstring[]required
min items: 1 · max items: 100
stage"alpha" | "beta" | "ga" | "disabled"required
created_atcustomrequired
updated_atcustomrequired
has_morefalserequired

Get custom role

GET/v1/projects/{project_id}/roles/{role_id}

Path parameters

project_idcustomrequired
role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$

Query parameters

No query parameters

Response

9 fields

namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
project_idcustomrequired
role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nullrequired
permissionsstring[]required
min items: 1 · max items: 100
stage"alpha" | "beta" | "ga" | "disabled"required
created_atcustomrequired
updated_atcustomrequired

Update custom role

PATCH/v1/projects/{project_id}/roles/{role_id}

Path parameters

project_idcustomrequired
role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$

Request body

titlestringoptional
min length: 1 · max length: 100
descriptionstring | nulloptional
permissionsstring[]optional
min items: 1 · max items: 100
stage"alpha" | "beta" | "ga" | "disabled"optional

Response

9 fields

namestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
project_idcustomrequired
role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nullrequired
permissionsstring[]required
min items: 1 · max items: 100
stage"alpha" | "beta" | "ga" | "disabled"required
created_atcustomrequired
updated_atcustomrequired

Delete custom role

DELETE/v1/projects/{project_id}/roles/{role_id}

Path parameters

project_idcustomrequired
role_idstringrequired
min length: 3 · max length: 64 · pattern: ^[a-z][a-zA-Z0-9._-]*$

Query parameters

No query parameters

Response

No response body

IAM policies

A GCP-style project IAM policy made of predefined role bindings.

Get IAM policy

POST/v1/projects/{project_id}/iamPolicy/get

Path parameters

project_idcustomrequired

Request body

Response

4 fields

version1required
etagstringrequired
min length: 1
bindingsobject[]required
rolestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
membersstring[]required
min items: 1
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
deny_rulesobject[]required
default: []
denied_permissionsstring[]required
min items: 1 · max items: 100
denied_principalsstring | "principalSet://socra/public:all"[]required
min items: 1
exception_principalsstring[]required
default: []
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000

Set IAM policy

POST/v1/projects/{project_id}/iamPolicy/set

Path parameters

project_idcustomrequired

Request body

policyobjectrequired
version1required
etagstringrequired
min length: 1
bindingsobject[]required
rolestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
membersstring[]required
min items: 1
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
deny_rulesobject[]optional
default: []
denied_permissionsstring[]required
min items: 1 · max items: 100
denied_principalsstring | "principalSet://socra/public:all"[]required
min items: 1
exception_principalsstring[]optional
default: []
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000

Response

4 fields

version1required
etagstringrequired
min length: 1
bindingsobject[]required
rolestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
membersstring[]required
min items: 1
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
deny_rulesobject[]required
default: []
denied_permissionsstring[]required
min items: 1 · max items: 100
denied_principalsstring | "principalSet://socra/public:all"[]required
min items: 1
exception_principalsstring[]required
default: []
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000

Test IAM permissions

POST/v1/projects/{project_id}/iamPolicy/testPermissions

Path parameters

project_idcustomrequired

Request body

permissionsstring[]required
min items: 1 · max items: 100
contextobjectoptional
request_timecustomoptional
resource_namestringoptional
max length: 500

Response

1 field

permissionsstring[]required

Account IAM policies

Inherited IAM allow and deny rules for every project in an account.

Get account IAM policy

POST/v1/accounts/{account_id}/iamPolicy/get

Path parameters

account_idcustomrequired

Request body

Response

4 fields

version1required
etagstringrequired
min length: 1
bindingsobject[]required
rolestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
membersstring[]required
min items: 1
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
deny_rulesobject[]required
default: []
denied_permissionsstring[]required
min items: 1 · max items: 100
denied_principalsstring | "principalSet://socra/public:all"[]required
min items: 1
exception_principalsstring[]required
default: []
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000

Set account IAM policy

POST/v1/accounts/{account_id}/iamPolicy/set

Path parameters

account_idcustomrequired

Request body

policyobjectrequired
version1required
etagstringrequired
min length: 1
bindingsobject[]required
rolestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
membersstring[]required
min items: 1
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
deny_rulesobject[]optional
default: []
denied_permissionsstring[]required
min items: 1 · max items: 100
denied_principalsstring | "principalSet://socra/public:all"[]required
min items: 1
exception_principalsstring[]optional
default: []
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000

Response

4 fields

version1required
etagstringrequired
min length: 1
bindingsobject[]required
rolestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
membersstring[]required
min items: 1
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
deny_rulesobject[]required
default: []
denied_permissionsstring[]required
min items: 1 · max items: 100
denied_principalsstring | "principalSet://socra/public:all"[]required
min items: 1
exception_principalsstring[]required
default: []
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000

IAM policy audit events

Immutable history of project IAM policy mutations.

List IAM policy audit history

GET/v1/projects/{project_id}/iamPolicy/audit

Path parameters

project_idcustomrequired

Query parameters

limitintegeroptional
min: 1 · max: 100

Response

2 fields

dataobject[]required
idstringrequired
project_idcustomrequired
actor_principalstringrequired
pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
action"policy.bootstrap" | "policy.set"required
previous_policyobject | nullrequired
policyobjectrequired
version1required
etagstringrequired
min length: 1
bindingsobject[]required
rolestringrequired
min length: 7 · max length: 256 · pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$
membersstring[]required
min items: 1
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
deny_rulesobject[]required
default: []
denied_permissionsstring[]required
min items: 1 · max items: 100
denied_principalsstring | "principalSet://socra/public:all"[]required
min items: 1
exception_principalsstring[]required
default: []
conditionobjectoptional
titlestringrequired
min length: 1 · max length: 100
descriptionstring | nulloptional
expressionstringrequired
min length: 1 · max length: 1000
created_atcustomrequired
has_morebooleanrequired

IAM authorization metrics

Per-permission authorization check, allow, and denial counters.

List IAM authorization metrics

GET/v1/projects/{project_id}/iamPolicy/metrics

Path parameters

project_idcustomrequired

Query parameters

Response

2 fields

dataobject[]required
permissionstringrequired
min length: 3 · max length: 256 · pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$
checksintegerrequired
min: 0 · max: 9007199254740991
allowedintegerrequired
min: 0 · max: 9007199254740991
deniedintegerrequired
min: 0 · max: 9007199254740991
has_morefalserequired

Service accounts

A project-owned non-human identity.

Create service account

POST/v1/projects/{project_id}/service-accounts

Path parameters

project_idcustomrequired

Request body

namestringrequired
min length: 1 · max length: 48 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Response

7 fields

idcustomrequired
project_idcustomrequired
principal_idstring | nullrequired
namestringrequired
min length: 1 · max length: 48 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
status"active" | "disabled"required
created_atcustomrequired
updated_atcustomrequired

List service accounts

GET/v1/projects/{project_id}/service-accounts

Path parameters

project_idcustomrequired

Query parameters

limitintegeroptional
min: 1 · max: 100
afterstringoptional

Response

2 fields

dataobject[]required
idcustomrequired
project_idcustomrequired
principal_idstring | nullrequired
namestringrequired
min length: 1 · max length: 48 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
status"active" | "disabled"required
created_atcustomrequired
updated_atcustomrequired
has_morebooleanrequired

Get service account

GET/v1/projects/{project_id}/service-accounts/{service_account_id}

Path parameters

project_idcustomrequired
service_account_idcustomrequired

Query parameters

No query parameters

Response

7 fields

idcustomrequired
project_idcustomrequired
principal_idstring | nullrequired
namestringrequired
min length: 1 · max length: 48 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
status"active" | "disabled"required
created_atcustomrequired
updated_atcustomrequired

Update service account

PATCH/v1/projects/{project_id}/service-accounts/{service_account_id}

Path parameters

project_idcustomrequired
service_account_idcustomrequired

Request body

status"active" | "disabled"optional

Response

7 fields

idcustomrequired
project_idcustomrequired
principal_idstring | nullrequired
namestringrequired
min length: 1 · max length: 48 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
status"active" | "disabled"required
created_atcustomrequired
updated_atcustomrequired

Delete service account

DELETE/v1/projects/{project_id}/service-accounts/{service_account_id}

Path parameters

project_idcustomrequired
service_account_idcustomrequired

Query parameters

No query parameters

Response

No response body

Service account keys

A replaceable credential for a service account.

Create service account key

POST/v1/projects/{project_id}/service-accounts/{service_account_id}/keys

Path parameters

project_idcustomrequired
service_account_idcustomrequired

Request body

Response

5 fields

idcustomrequired
service_account_idcustomrequired
secret_hintstringrequired
secretstringoptional
created_atcustomrequired

List service account keys

GET/v1/projects/{project_id}/service-accounts/{service_account_id}/keys

Path parameters

project_idcustomrequired
service_account_idcustomrequired

Query parameters

Response

2 fields

dataobject[]required
idcustomrequired
service_account_idcustomrequired
secret_hintstringrequired
secretstringoptional
created_atcustomrequired
has_morebooleanrequired

Delete service account key

DELETE/v1/projects/{project_id}/service-accounts/{service_account_id}/keys/{key_id}

Path parameters

project_idcustomrequired
service_account_idcustomrequired
key_idcustomrequired

Query parameters

No query parameters

Response

No response body