--- title: "Using IAM policies with OVHcloud API" description: "Learn how to provide specific access rights to users of an OVHcloud account." url: https://docs.us.ovhcloud.com/en/manage-and-operate/iam/using-policies-ovhcloud-api lang: en --- > For AI agents: the complete documentation index is available at https://docs.us.ovhcloud.com/en/llms.txt, the full documentation bundle is available at https://docs.us.ovhcloud.com/en/llms-full.txt. # Using IAM policies with OVHcloud API **Learn how to provide specific access rights to users of an OVHcloud account.** The access management of OVHcloud is based on a "policy" management system. It is possible to write different "policies" that give users access to specific features on the products linked to an OVHcloud account. In detail, a policy contains: - One or more **identities** targeted by this policy. - Identities can be account IDs, users, or user groups (like the ones used in [Federation](https://docs.us.ovhcloud.com/en/account/account-information/sso-active-directory-federation-services.md)). - One or more **resources** impacted by this policy. - A resource is an OVHcloud product that will be impacted by this policy (a domain name, a Nutanix server, a Load Balancer, etc.). - One or more **actions** allowed, denied, or excepted by this policy. - Actions are the specific rights affected by this policy (reboot the server, create an email account, terminate a product, etc.) For instance, we can create a policy to give a VPS user, named John, access to the action "reboot". **This guide explains in detail how these policies can be declared using the OVHcloud API, and how to list the identities, resources, and actions available for them.** ## Requirements To set up a policy, you will require: - an [OVHcloud account](https://docs.us.ovhcloud.com/en/account/account-information/create-account.md) - to know [how to manage account users](https://docs.us.ovhcloud.com/en/account/account-information/manage-local-users.md) - some OVHcloud products linked to this OVHcloud account (Load Balancer, domain name, VPS, etc.)   ## Instructions ### Policies This first part describes how to create and update policies. Resources, resource groups, and actions needed to create a policy will be described in the next sections. #### API definition | **API Call** | **Description** | | ------------------------------------------------------------------------------------------------------- | ------------------------- | | `GET /iam/policy` | Retrieve all policies | | `POST /iam/policy` | Create a new policy | | `GET /iam/policy/{policyId}` | Retrieve the given policy | | `PUT /iam/policy/{policyId}` | Update an existing policy | | `DELETE /iam/policy/{policyId}` | Delete the given policy |   #### Retrieve all policies The following example shows how a policy is built. Find all policies, including those pre-generated by OVHcloud, by calling the API call: [GET /iam/policy](https://api.us.ovhcloud.com/console/?section=/iam&branch=v2#get-/iam/policy) _Example output:_ **/iam/policy** ```json [ { "id": "69470db1-5372-4e32-acf1-edc2afd84c12", "owner": "xx1111-ovh", "name": "ovh-default", "readOnly": true, "identities": [ "urn:v1:us:identity:account:xx1111-ovh" ], "resources": [ { "urn": "urn:v1:us:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8" } ], "permissions": { "allow": [ { "action": "*" } ] }, "createdAt": "2023-01-27T11:29:22.197537Z", "updatedAt": "2023-01-27T11:29:22.197537Z" } ] ``` In this example, the account "_urn:v1:us:identity:account:xx1111-ovh_" can do every action (_"action":"\*"_) to the group of resources "_urn:v1:us:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8_". This policy is owned by "_xx1111-ovh_" (it corresponds to the admin role, is created by OVHcloud, and cannot be modified). Items in policies are defined by URNs. The URN can use a `*` wildcard at the beginning or at the end of it. These URNs are defined by the following pattern: |   | **urn** | **:** | **version** | **:** | **plate** | **:** | **type** | **:** | **sub-type** | **:** | **id** | | -------------------------- | ---------------- | ----- | ------------------------- | ----- | ------------------------------ | ----- | --------------------------------- | ----- | ---------------------------------------------------------------------------------- | ----- | --------------------------------------- | | **Description** | immutable prefix | : | version of the IAM system | : | Plate where the urn is located | : | Type of the current urn | : | (optional) Subtype for **identity** or **resource** type | : | Unique identifier associated to the urn | | **Possible values** | urn | : | v1 | : | eu, ca, us | : | identity, resource, resourceGroup | : | For **identity** type: account, user, groupFor **resource** type: any resourceType | : | Alphanumerical value | | **Account ID Example** | urn | : | v1 | : | us | : | identity | : | account | : | xx1111-ovh | | **User group Example** | urn | : | v1 | : | us | : | identity | : | group | : | xx1111-ovh/admin\@mycompany.com | | **VPS Example** | urn | : | v1 | : | us | : | resource | : | vps | : | vps-5b48d78b.vps.ovh.us | | **Resource Group Example** | urn | : | v1 | : | us | : | resourceGroup |   |   | : | aa0713ab-ed13-4f1a-89a5-32aa0cb936d8 | The URNs and actions can end with a `*` wildcard character. This allows referring to multiple resources, identities, or actions in a single line. _Example of a resource URN with a wildcard:_ `urn:v1:us:resource:vps:*` will match any vps resource _Example of an action with a wildcard:_ `vps:apiovh:*` will match any action of the vps type.   #### Policy attributes - **id**: Unique identifier of the policy. It follows the UUID format. - **owner**: The account that created this policy. - **name**: The policy name. It's possible to use this name to organize the policies. There is no format to follow (except that the prefix "ovh-" is reserved for OVHcloud policies). - **readOnly**: If true, it indicates that the policy cannot be edited. It often represents policies managed by OVHcloud. - **identities**: The identities concerned by the policy. They are specified by a URN. **account**:**account-id** for the account, **user**:**account-id**/**username** for an account user, **group**:**account-id**/**username** for a user group. - **resources**: The resources concerned by the policy. They are specified by a URN. **resource** for a resource, **resourceGroup** for a resource group. - **permissions**: Can be **allow** or **except**: - **allow**: Array of actions allowed for the identities regarding the resources. All actions are denied by default. - **deny:** Array of actions explicitly denied for the identities regarding the resources. A denied action will be prevented no matter what other policies might allow. - **except**: Extension of the **allow** parameter. Array of actions not to allow even though they are included in the **allow** actions. For instance, this is useful when there is a wildcard allow action but it's necessary to exclude a specific action that otherwise would be included in the wildcard. Contrary to **deny**, **except** is limited to the current policy scope. - **permissionGroups:** List of [permission groups](https://docs.us.ovhcloud.com/en/account/account-information/iam-permission-groups.md) applied to this policy. - **conditions:** List conditions applied to the policy. - **expiredAt:** Date after which the policy will be disabled. - **createdAt**: Creation date of the policy. - **updateAt**: Last update date of the policy.   #### Create a policy Create a new policy using this API route: [POST /iam/policy](https://api.us.ovhcloud.com/console/?section=/iam&branch=v2#post-/iam/policy) For example, create a policy to authorize a user named "_user1_" to do some actions on a VPS: **Warning:** **NOTE:** This example is specific to VPS. To see other possible resources you can use, see the [Resources section](#resources). **create policy example** ```json { "description": "VPS - reboot and create snapshot", "identities": [ "urn:v1:us:identity:user:xx1111-ovh/user1" ], "name": "vps-reboot-snapshot", "permissions": { "allow": [ { "action": "vps:apiovh:reboot" }, { "action": "vps:apiovh:snapshot/create" } ] }, "resources": [ { "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us" } ] } ``` This policy is not for an account but for a user, so the identity URN corresponds to the format "\*urn:v1:us:identity:**user**:**account-id**/\*_username_\*\*". ```json { "description": "VPS - all except delete snapshot", "identities": [ "urn:v1:us:identity:user:xx1111-ovh/user2" ], "name": "vps-all-but-delete-snapshot", "permissions": { "allow": [ { "action": "vps:apiovh:*" } ], "except": [ { "action": "vps:apiovh:snapshot/delete" } ] }, "resources": [ { "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.net" } ] } ``` This policy uses a wildcard with an except. This allows you to easily give a large set of permissions. Here the user `user2` will have all permissions of the **vps** type on `vps-5b48d78b.vps.ovh.us` except for the permission to delete a snapshot. The policy will be created with this JSON as the body for the call: [POST /iam/policy](https://api.us.ovhcloud.com/console/?section=/iam&branch=v2#post-/iam/policy) Check it via: [GET /iam/policy](https://api.us.ovhcloud.com/console/?section=/iam&branch=v2#get-/iam/policy) **GET /iam/policy** ```json [ { "id": "69470db1-5372-4e32-acf1-edc2afd84c12", "owner": "xx1111-ovh", "name": "ovh-default", "readOnly": true, "identities": [ "urn:v1:us:identity:account:xx1111-ovh" ], "resources": [ { "urn": "urn:v1:us:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8" } ], "permissions": { "allow": [ { "action": "*" } ] }, "createdAt": "2023-01-27T11:29:22.197537Z", "updatedAt": "2023-01-27T11:29:22.197537Z" }, { "id": "9dfe6a03-1937-4287-8ab7-866224d333b1", "owner": "xx1111-ovh", "name": "vps-reboot-snapshot", "readOnly": false, "description": "VPS - reboot and create snapshot", "identities": [ "urn:v1:us:identity:user:xx1111-ovh/user1" ], "resources": [ { "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us" } ], "permissions": { "allow": [ { "action": "vps:apiovh:reboot" }, { "action": "vps:apiovh:snapshot/create" } ] }, "createdAt": "2023-02-07T15:24:57.680037Z" }, { "id": "73a220d0-8346-4d4a-bdab-c0f671d62368", "owner": "xx1111-ovh", "name": "vps-all-but-delete-snapshot", "readOnly": false, "description": "VPS - all except delete snapshot", "identities": [ "urn:v1:us:identity:user:xx1111-ovh/user2" ], "resources": [ { "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us" } ], "permissions": { "allow": [ { "action": "vps:apiovh:*" } ], "except": [ { "action": "vps:apiovh:snapshot/delete" } ] }, "createdAt": "2023-02-07T15:32:18.957023Z" } ] ``` The policies have been created successfully. Now, "_**user1**_" can **carry out reboots and create snapshots** on the VPS "_**urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us**_". "_**user2**_" can **execute any vps action except for the deletion of snapshots** on the VPS "_**urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us**_".   #### Conditions It is possible to add conditions to policies. The policy will only be valid if the conditions are met. Conditions are added to an access policy in the following form: ```json { "operator": "AND", "conditions": [ { "operator": "MATCH", "values": { "resource.Tag(environment)": "prod", "resource.Type": "vps" } }, { "operator": "NOT", "conditions": [ { "operator": "MATCH", "values": { "date(America/New_York).WeekDay.IN": "Saturday,Sunday" } } ] } ] } ``` For example, a policy with this condition is valid if the targeted resources are of type **vps** with the tag **"environment:prod"**, except on **Saturday and Sunday** in the New York time zone. The operator field specifies how the conditions will be evaluated: - **AND**: All conditions must be validated - **NOT**: None of the conditions must be validated - **OR**: At least one condition must be validated - **MATCH**: Condition evaluation operator The available conditions are: | Condition | Operator | Data Type | Description | Example | | ---------------------- | ------------------------------ | ---------- | -------------------------- | ------------------------------------------------- | | date(location).Date | EQ BEFORE AFTER IN | YYYY-MM-DD | Filter on calendar days | "date.Date(America/New\_York)": "2024-12-25" | | date(location).Hour | EQ BEFORE AFTER GE LE GT LT IN | int | Filter on hours | "date(America/New\_York).Hour.IN" : "7,8,9" | | date(location).WeekDay | EQ BEFORE AFTER GE LE GT LT IN | string | Filter on days of the week | "date(America/New\_York).WeekDay.AFTER": "monday" | | resource.Tag(tag\_key) | EQ STARTS\_WITH ENDS\_WITH | string | Filter on tags | "resource.Tag(environment): "dev" | | resource.Name | EQ IN STARTS\_WITH ENDS\_WITH | string | Filter on resource names | "resource.Name.Start\_with": "vps-" | | resource.Type | EQ IN STARTS\_WITH ENDS\_WITH | string | Filter on resource types | "resource.Type.In": "vps" | | request.IP | EQ IN IN\_RANGE | IPv4 | Filter on client source IP | "request.IP.IN\_RANGE": "10.23.0.0/16" | Dates use time zones based on [IANA database names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If not specified, the date will be evaluated in UTC time zone. The available operators for condition types are: - **EQ**: The value must exactly match the specified value - **BEFORE** or **LT** (less than): The value must be strictly less than - **AFTER** or **GE** (greater or equal): The value must be equal to or greater than - **GT** (greater than): The value must be strictly greater than - **LE** (less or equal): The value must be equal to or less than - **IN**: The value must be included in the list - **START\_WITH**: The value must start with the specified value - **END\_WITH**: The value must end with the specified value - **IN\_RANGE**: The value must be in the specified IP subnet If not specified, the default operator is **EQ**.   ### Identities Policies apply to users, which can be accounts, users, or user groups. This section describes how to retrieve or create a user for the policy. #### API definitions | **API Call** | **Description** | | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `GET /me/identity/user` | Retrieve all users of this account | | `POST /me/identity/user` | Create a new user | | `GET /me/identity/user/{user}` | Get details of this specific user | | `PUT /me/identity/user/{user}` | Alter a user | | `DELETE /me/identity/user/{user}` | Delete a user | | `GET /me/identity/group` | Retrieve all groups of this account | | `POST /me/identity/group` | Create a new group | | `GET /me/identity/group/{group}` | Get details of this specific group | | `PUT /me/identity/group/{group}` | Alter a group | | `DELETE /me/identity/group/{group}` | Delete a group |   #### Create users List all the current users related to the account by calling: **/me/identity/user** ```json [ "user1", "user2" ] ``` These users can be used on policies with the URN format: urn:v1:us:identity:user:**xx1111-ovh**/**user1** To create a new user, call the API route with the following body: **post /me/identity/user** ```json { "description": "string", "email": "string", "group": "string", "login": "string", "password": "" } ```   #### Create user groups List all the current user groups related to the account by calling: **/me/identity/group** ```json [ "ADMIN", "DEFAULT", "UNPRIVILEGED", "admin@mycompany.com" ] ``` These user groups can be used on policies with the URN format: urn:v1:us:identity:group:**xx1111-ovh**/**[admin@mycompany.com](mailto:admin@mycompany.com)** To create a new user group, call the API route with the following body: **post /me/identity/group** ```json { "description": "string", "name": "string", "role": "REGULAR" } ``` For more information, refer to the [documentation for user management](https://docs.us.ovhcloud.com/en/account/account-information/manage-local-users.md).   #### With SSO connection enabled If the federation is enabled through the [SSO connection](https://docs.us.ovhcloud.com/en/account/account-information/sso-active-directory-federation-services.md), policies only apply to user groups as described in the previous section.   ### Resources Policies refer to **resources.** The resources are all OVHcloud products subscribed to by the OVHcloud account that can be controlled by this account. This section describes how to retrieve resources information to use in a policy. #### API definition | **API Call** | **Description** | | -------------------------------------------------------------------------------------------------------- | ------------------- | | `GET /iam/resource` | List all resources | | `GET /iam/resource/{resourceId}` | Retrieve a resource |   #### Example See all the resources linked to the OVHcloud account by calling: **/iam/resource** ```json [ { "id": "b96ffed4-3467-4129-b8be-39a3eb3a0a93", "urn": "urn:v1:us:resource:vps:vps-5b48d78b.vps.ovh.us", "name": "vps-5b48d78b.vps.ovh.us", "displayName": "vps-5b48d78b.vps.ovh.us", "type": "vps", "owner": "xx1111-ovh" }, { "id": "c24ace5e-6c9c-436b-9a73-515db8df6250", "urn": "urn:v1:us:resource:emailDomain:acme.com", "name": "acme.com", "displayName": "acme.com", "type": "emailDomain", "owner": "xx1111-ovh" }, { "id": "8d70a49b-7a8b-4ec0-ad4b-756da802d994", "urn": "urn:v1:us:resource:cdn:cdn-46.105.198.89-12969", "name": "cdn-46.105.198.89-12969", "displayName": "cdn-46.105.198.89-12969", "type": "cdn", "owner": "xx1111-ovh" } ] ``` In this example, the account has three resources available (a VPS, an email domain, and a CDN). Each of these resources has a set of attributes to identify them on policies.   #### Resource attributes - **id**: Unique identifier of the resource. It follows the UUID format. - **urn**: Resource URN. - **name**: The resource name. - **displayName**: The resource name as displayed in the user interface. - **type**: The resource type (vps, publicCloudProject, dnsZone, domain, emailDomain, etc.). - **owner**: The resource owner (Account ID).   ### Resource Groups To ease policy management for a large number of resources, it is possible to set up a resource group that aggregates several resources to a unique URN. #### API definitions | **API Call** | **Description** | | ------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `GET /iam/resourceGroup` | Retrieve all resource groups | | `POST /iam/resourceGroup` | Create a new resource group | | `GET /iam/resourceGroup/{groupId}` | Retrieve the given resource group | | `PUT /iam/resourceGroup/{groupId}` | Update an existing resource group | | `DELETE /iam/resourceGroup/{groupId}` | Delete the given resource group |   #### Retrieve a resource group List all resource groups by calling **/iam/resourceGroup**. This API route can be called with a query-string parameter "details" to expand the results with all the attributes of the returned resources. _Example output:_ **/iam/resourceGroup** ```json [ { "id": "aa0713ab-ed13-4f1a-89a5-32aa0cb936d8", "urn": "urn:v1:us:resourceGroup:aa0713ab-ed13-4f1a-89a5-32aa0cb936d8", "readOnly": true, "name": "myVPS", "owner": "xx1111-ovh", "resources": [ { "id": "b96ffed4-3467-4129-b8be-39a3eb3a0a93" }, { "id": "7a19dbca-7da5-460f-a59b-69d56e57bf9d" }, { "id": "50423397-8984-4d44-8505-fdd489c2c9fb" } ], "updatedAt": "2023-01-27T11:29:22.197537Z", "createdAt": "2023-01-27T11:29:22.197537Z" } ] ``` #### Resource group attributes - **id**: Unique identifier of the resource group. It follows the UUID format. - **urn**: Resource group URN to use on the policy. - **readOnly**: Cannot be modified if `true`. The default resource groups are read-only. - **name**: The resource group name. - **owner**: The resource group owner (Account ID). - **resources**: - If details = **false**: Array of resources UUID. - If details = **true**: The resources will be expanded with their attributes (as the result we have via the resource API). - **createdAt**: Creation date of the resource group. - **updateAt**: Last update date of the resource group.   #### Create a resource group API definition | **API Call** | **Description** | | ----------------------------------------------------------------------------------------------- | --------------------------- | | `POST /iam/resourceGroup` | Create a new resource group |   Example The following example creates a resource group called "_Test\_environment_" containing two resources: ```json { "name": "Test_environment", "resources": [ { "id": "b10611a9-7cc1-40b7-8475-18aabcdffc62" }, { "id": "53f815b1-c020-4e5d-8239-fbbcaaca1742" } ] } ```   ### Action Policies contain a list of **Actions** that will be allowed or denied to users. These actions are specific to every product, such as rebooting a database server, ordering an upgrade, restoring a snapshot, etc. #### API definition | **API Call** | **Description** | | ------------------------------------------------------------------------------------------------- | -------------------- | | `GET /iam/reference/action` | Retrieve all actions |   #### Example List all the actions available for policies with the API, for example: **action example** ```json { "action": "vps:apiovh:reboot", "description": "Request a reboot of the machine", "resourceType": "vps", "categories": [ "OPERATE" ] } ``` This action is "_vps:apiovh:reboot_", it targets the ability to reboot a VPS. The call to **/iam/reference/action** will list **all of the available** actions (WARNING: This contains a huge amount of items). It is strongly recommended to specify the **resourceType** as a query-string parameter for this API call (see the next section).   #### Action attributes - **action**: The action itself. - **description**: The action description. - **resourceType**: The resource type targeted by this action. - **categories**: The categories of this action (CREATE, READ, EDIT, OPERATE, DELETE).   #### Permission group OVHcloud provides permission groups that group together all of the actions required for specific use cases. Permission groups are accessible via the following API: | **API Call** | **Description** | | ------------------------------------------------------------------------------------------------- | ------------------------------ | | `GET /iam/permissionsGroup` | Retrieve all permission groups | ```json { "id": "00000000-0000-0000-0001-000000000001", "urn": "urn:v1:us:permissionsGroup:ovh:globalAdmin", "name": "globalAdmin", "owner": "ovh", "description": "Give global admin access across all OVHcloud products", "permissions": { "allow": [ { "action": "*" } ] }, "createdAt": "2023-03-14T09:10:57.40418Z", "updatedAt": null }, ``` These permission groups can then be used in addition to or in place of unitary actions in access policies: ```json { "description": "", "identities": [...], "name": "", "permissions": { "allow": [ { "action": "..." }, ] }, "permissionsGroups": [ { "urn": "urn:v1:us:permissionsGroup:ovh:globalAdmin" } ], "resources": [...] } ``` A full description of the permission groups can be found in our [dedicated documentation](https://docs.us.ovhcloud.com/en/account/account-information/iam-permission-groups.md).   ### Resource types #### API definition | **API Call** | **Description** | | -------------------------------------------------------------------------------------------------------- | --------------------------- | | `GET /iam/reference/resource/type` | Retrieve all resource types |   #### Example Here is a part of the output: **/iam/reference/resource/type** ```json [ "account", "packXdsl", "cloudDB", "loadbalancer", "mxplanAccount", "publicCloudProject", "voipSmsvn", "vps", ] ```   ## Go further Browse all the [IAM guides](https://docs.us.ovhcloud.com/en/manage-and-operate/iam/landing-page-iam.md). Browse the rest of the [OVHcloud US documentation](https://docs.us.ovhcloud.com/en/index.md) for guides on our other products and services.