NavigationContentFooter

IAM API

Introduction

Identity and Access Management (IAM) allows you to share access to the management of your Scaleway resources and Organization settings, in a controlled and secure manner. With IAM, you can invite other users to your Organization, as well as create IAM applications which represent non-human users with their own API keys. You define permissions for users and applications in your Organization via highly customizable policies. Policies let you specify exactly what rights users and applications (or groups of users and applications) should have within your Organization.

Concepts

Refer to our to find definitions of the different terms referring to IAM.

Quickstart

  1. Configure your environment variables.

    export ACCESS_KEY="<access-key>"
    export SECRET_KEY="<secret-key>"
    export REGION="<region>"
  2. Create an application. Replace the parameter values in the request payload with the details of your new application.

    Note

    The UUIDs used in the following code examples are not real

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" https://api.scaleway.com/iam/v1alpha1/applications \
    -d '{
    "name": "prod1",
    "organization_id": "c6842bac-7938-4c04-9e03-f48147eee1f1",
    "description": "this is my new application"
    }'
    ParameterDescription
    nameREQUIRED The name of your new application
    organization_idThe ID of your Scaleway Organization
    descriptionThe description of your application
  3. Retrieve your application ID from the response.

    {
    "id": "950dde46-5cba-427d-a4f5-ce5a8a79717c",
    "name": "prod1",
    "description": "this is my new application",
    "created_at": "2023-03-08T12:34:56.123456Z",
    "updated_at": "2023-03-08T12:34:56.123456Z",
    "organization_id": "c6842bac-7938-4c04-9e03-f48147eee1f1",
    "editable": "true",
    "nb_api_keys": "0"
    }
  4. Create a policy. Replace the parameter values in the request payload with the details of your new application, including the application ID retrieved in the previous step.

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" https://api.scaleway.com/iam/v1alpha1/policies \
    -d '{
    "name": "policy-prod1",
    "description": "This policy grants full access to IAM in my Organization to application prod1",
    "organization_id": "c6842bac-7938-4c04-9e03-f48147eee1f1",
    "rules": [
    {
    "permission_set_names": [
    "IAMManager"
    ],
    "organization_id": "c6842bac-7938-4c04-9e03-f48147eee1f1"
    }
    ],
    "application_id": "950dde46-5cba-427d-a4f5-ce5a8a79717c"
    }'
    ParameterDescription
    nameREQUIRED The name of your new application
    descriptionThe description of your policy
    organization_idThe ID of your Scaleway Organization
    rulesThe of your policy
    permission_set_namesThe permission sets you want to grant. You can either or find a complete list in the
    organization_idThe ID of the Scaleway Organization where you want your permission sets to apply. You can add one as the of your policy
    application_idThe ID of your application
    Note

    To learn more about IAM policies, refer to our dedicated .

  5. Create an API key for your application.

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" https://api.scaleway.com/iam/v1alpha1/api-keys \
    -d '{
    "application_id": "950dde46-5cba-427d-a4f5-ce5a8a79717c",
    "expires_at": "2023-12-22T12:34:56.123456Z",
    "default_project_id": "2aeadddc-c589-4784-8ef5-fae989a4bac8",
    "description": "This is an API key for prod1"
    }'
    ParameterDescription
    application_idThe ID of your application
    expires_atOPTIONAL The expiration date of your API key
    default_project_idOPTIONAL The Project ID of your preferred Project, to use with Object Storage. If no Project ID is specified, the default project is used. Refer to the
    descriptionThe description of your API key
  6. Retrieve your access and secret keys from the response.

    Note

    The secret key is only showed once. Make sure that you copy and store both keys somewhere safe.

You can now have an IAM configuration fully set up and can begin working on your Scaleway projects.

Requirements

To perform the following steps, you must first ensure that:

  • you have an account and are logged into the
  • you have created an and that the API key has sufficient to perform the actions described on this page.
  • you have

Technical Limitations

  • Currently, IAM users cannot be created within Scaleway Organizations, they can only be invited to join them. Refer to the to learn more about users.

  • Access management at ressource level is not yet available. You can currently scope the permission sets to a Project or to an Organization. Refer to the to learn more about permission sets.

  • Explicit deny permissions are not yet available. You can currently only explicitely allow access to different products or Organization management features.

Going Further

For more information about IAM, you can check out the following pages:

  • join the #iam channel
  • .

SSH Keys

An SSH Key (Secure Shell Key) allows passwordless connection to an . An SSH Key is , consisting of a sensitive identification key, (aka private key) which must be stored securely, and a public key which is uploaded to the Scaleway interface.

The public key is kept in your Scaleway account and transferred to the Instance during the boot process, while the identification key is kept securely on your local computer. When connecting to the Instance via SSH, a trusted connection to the machine is established using the key pair.

GET
/iam/v1alpha1/ssh-keys
POST
/iam/v1alpha1/ssh-keys
GET
/iam/v1alpha1/ssh-keys/{ssh_key_id}
PATCH
/iam/v1alpha1/ssh-keys/{ssh_key_id}
DELETE
/iam/v1alpha1/ssh-keys/{ssh_key_id}

Groups

A group (also known as an IAM group) is a grouping of and/or . Creating groups allows you to attach to multiple users and/or applications at the same time.

GET
/iam/v1alpha1/groups
POST
/iam/v1alpha1/groups
GET
/iam/v1alpha1/groups/{group_id}
PATCH
/iam/v1alpha1/groups/{group_id}
DELETE
/iam/v1alpha1/groups/{group_id}
POST
/iam/v1alpha1/groups/{group_id}/add-member
POST
/iam/v1alpha1/groups/{group_id}/add-members
PUT
/iam/v1alpha1/groups/{group_id}/members
POST
/iam/v1alpha1/groups/{group_id}/remove-member

API Keys

An API key is a unique identifier, used to authenticate requests made to the Scaleway API. An API key consists of an access key and a secret key. The access key is like a unique ID or username, and not a sensitive piece of information. The secret key however is more sensitive, as it is like a password to authenticate the access key.

Previously, an API key was associated with a single Scaleway . The API key therefore had full read/write access to all resources on this Project, and only this Project.

With IAM, an API key is now associated with an IAM or . This allows fine-grained access to be defined for the IAM user bearing the API key across different Organizations, Projects, and resources.

GET
/iam/v1alpha1/api-keys
POST
/iam/v1alpha1/api-keys
GET
/iam/v1alpha1/api-keys/{access_key}
PATCH
/iam/v1alpha1/api-keys/{access_key}
DELETE
/iam/v1alpha1/api-keys/{access_key}

Users

A user (also known as an IAM user) is a human user in an Organization. They can either be the Owner of the Organization linked to their Scaleway account, or a Guest in a different Organization. Within each Organization, different IAM users can have different rights (defined through IAM policies) to perform actions on resources.

GET
/iam/v1alpha1/users
POST
/iam/v1alpha1/users
GET
/iam/v1alpha1/users/{user_id}
PATCH
/iam/v1alpha1/users/{user_id}
DELETE
/iam/v1alpha1/users/{user_id}

Applications

An application (also known as an IAM application) is a non-human user in a Scaleway Organization. IAM applications may be used when you want to create an API key that is not linked to a user, to give programmatic access to resources.

Note that applications cannot, by definition, have access to the Scaleway console, as they have only an API key and no account themselves (they are not ).

GET
/iam/v1alpha1/applications
POST
/iam/v1alpha1/applications
GET
/iam/v1alpha1/applications/{application_id}
PATCH
/iam/v1alpha1/applications/{application_id}
DELETE
/iam/v1alpha1/applications/{application_id}

Policies

Policies control user rights, by defining one or more rules to apply to the attached principals (users, groups or applications). A policy rule has two parts:\ permission set and scope.

For each policy rule, you specify one or more permission sets (eg. “list all Instances”) and their scope (eg. “on Project A only”). This therefore defines the actions that the principles can carry out on resources within the scope.

GET
/iam/v1alpha1/policies
POST
/iam/v1alpha1/policies
GET
/iam/v1alpha1/policies/{policy_id}
PATCH
/iam/v1alpha1/policies/{policy_id}
DELETE
/iam/v1alpha1/policies/{policy_id}
POST
/iam/v1alpha1/policies/{policy_id}/clone

Rules

A rule (also known as an IAM rule) is the part of a that defines the permissions of the policy's , and the scope of these permissions. A policy can have one or many rules. Each rule consists of:

  • A scope, which defines where the permission sets should apply. At Scaleway, a scope can be at or level.

    • Projects group your Scaleway resources (eg. Instances, Object Storage buckets, Managed Databases etc.) together. An Organization may have many Projects, or just one default Project. If you choose to define scope at Project level, you can select one, many, or all Projects. When you then define the for this scope, you can give access to different resources within the Project(s).
    • An Organization is made of one or several Projects. Billing, IAM, Project management and support are all managed at Organization level, so choose the Organization scope to give access to these features.
  • One or more (eg. "list all Instances"). A permission set consists of one or multiple to perform actions on resources or features. Each permission set has a clear description, e.g. InstancesFullAccess, InstancesReadOnly, RelationalDatabasesFullAccess, BillingReadOnly.

GET
/iam/v1alpha1/rules
PUT
/iam/v1alpha1/rules

Permission sets

Permission sets are the main components of . They consist of sets of one or multiple .

Permission set names contain descriptions that clearly explain their purpose. For example, a permission set that grants access to all actions you can perform on Instances is called:\ InstancesFullAccess.

Permissions sets (eg.InstanceReadAccess) and their (eg. "on Project A only") make up IAM rules, which define the access rights that a (user, group or application) should have.

GET
/iam/v1alpha1/permission-sets

Quotas

Every Scaleway Organization detains a certain number of resource quotas, which are limits on the number of Scaleway resources these Organizations can use.

GET
/iam/v1alpha1/quota
GET
/iam/v1alpha1/quota/{quotum_name}

JWTs

GET
/iam/v1alpha1/jwts
GET
/iam/v1alpha1/jwts/{jti}
DELETE
/iam/v1alpha1/jwts/{jti}

Logs

Logs provide a record of all events and errors that take place during the lifecycle of your IAM resources (IAM users, applications, groups, API keys, and policies). Logs represent a source of visibility if you want to know when a problem occurred, or which events correlate with it.

GET
/iam/v1alpha1/logs
GET
/iam/v1alpha1/logs/{log_id}
© 2023-2024 – Scaleway