openapi: 3.0.0
info:
  title: Audit Trail API
  description: |-
    Scaleway Audit Trail is a tool that holds a record of events and changes performed within a Scaleway Organization. It helps you ensure accountability and security by recording activity across all your resources (identity of the principal, date of activity, source IP address, API method used, and status of the request).

    You can use Audit Trail for troubleshooting, compliance verification, and analysis in the event of a breach.

    (switchcolumn)
    (switchcolumn)

    ## Concepts

    Refer to our [dedicated concepts page](https://www.scaleway.com/en/docs/identity-and-access-management/audit-trail/concepts/) to find definitions of the different terms referring to Audit Trail.

    (switchcolumn)
    (switchcolumn)

    ## Quickstart

    To start using Audit Trail you need to configure the `AuditTrailReadOnly` or the `OrganizationManager` permission sets in [IAM](https://www.scaleway.com/en/docs/identity-and-access-management/iam/concepts/#iam).
    The `OrganizationManager` permission set is included in the `Administrator` group which is created by default whenever a new Organization is created.
    The [scope](https://www.scaleway.com/en/docs/identity-and-access-management/iam/concepts/#scope) of these permission sets is at [Organization](https://www.scaleway.com/en/docs/identity-and-access-management/iam/concepts/#organization) level.

    1. Configure your environment variables.

        <Message type="note">
        This is an optional step that seeks to simplify your usage of the Audit Trail API.
        </Message>

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

        ```bash
            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-audit-trail",
            "description": "This policy grants read access to Audit Trail in my Organization to the user matching the userID defined below",
            "organization_id": "123e4567-e89b-12d3-a456-426614174000",
            "rules": [
                {
                "permission_set_names": [
                    "AuditTrailReadOnly"
                ],
                "organization_id": "123e4567-e89b-12d3-a456-426614174000"
                }
            ],
            "user_id": "987f6543-21ba-43dc-b678-567812345678"
            }'

        ```

        | Parameter        | Description                                   |
        | :--------------- | :--------------------------------------       |
        | `name`           | **REQUIRED** The name of your new policy |
        | `description`| The description of your policy          |
        | `organization_id`| The ID of your Scaleway Organization |
        | `rules`| The [rules](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/policy/#rules) of your policy |
        | `permission_set_names` | The permission sets you want to grant. You can either [list all permission sets using the IAM API](https://www.scaleway.com/en/developers/api/iam/#path-permission-sets-list-permission-sets) or find a complete list in the [permission sets documentation page](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/permission-sets/) |
        | `organization_id`| The ID of the Scaleway Organization where you want your permission sets to apply. You can add one as the [scope](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/policy/#scope) of your policy |
        | `user_id`| The ID of the user you are granting access to |

        <Message type="note">
        To learn more about IAM policies, refer to our dedicated [IAM policies reference page](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/policy/).
        </Message>

    3. Run the following command to retrieve the list of Scaleway products for which you have Audit Trail events.

            ```bash
            curl --request GET \
                --url https://api.scaleway.com/audit-trail/v1alpha1/$REGION/fr-par/products \
                --header "X-Auth-Token: $SCW_SECRET_KEY"
            ```

    4. Run the following command to list your Audit Trail events.

            ```bash
            curl --request GET \
                --url "https://api.scaleway.com/audit-trail/v1alpha1/regions/$REGION/events?organization_id=123e4567-e89b-12d3-a456-426614174000" \
                --header "X-Auth-Token: $SCW_SECRET_KEY"

            ```
        <Message type="note">
        Only events that happened within the last hour will be returned in the output. If no events appear, make sure that you have created Scaleway resources in the targeted region. Find out more about [troubleshooting Audit Trail issues](https://www.scaleway.com/en/docs/identity-and-access-management/audit-trail/troubleshooting/cannot-see-events) in our dedidcated documentation.
        </Message>

    (switchcolumn)

    <Message type="requirement">
     - You have your [Organization and your Project ID](https://console.scaleway.com/project/settings)
     - You have [created an API key](https://www.scaleway.com/en/docs/identity-and-access-management/iam/how-to/create-api-keys/)
     - You have [installed `curl`](https://curl.se/download.html)
     - You have created an [API key](https://www.scaleway.com/en/docs/identity-and-access-management/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/permission-sets/) to perform the actions described on this page
     - You have created [Scaleway products integrated with Audit Trail](https://www.scaleway.com/en/docs/identity-and-access-management/audit-trail/reference-content/resource-integration-with-adt)
    </Message>

    (switchcolumn)

    ## Technical information

    ### Regions

    Scaleway's infrastructure spans different [regions and Availability Zones](https://www.scaleway.com/en/docs/console/my-account/reference-content/products-availability/).

    Audit Trail is available in the Paris, and Amsterdam regions, which are represented by the following path parameters:

    - fr-par
    - nl-ams

    ## Technical limitations

    Audit Trail is only integrated with [Secret Manager](https://www.scaleway.com/en/developers/api/secret-manager/). Find out about product integration with Audit Trail in our [dedicated documentation](https://www.scaleway.com/en/docs/identity-and-access-management/audit-trail/reference-content/resource-integration-with-adt).

    ## Going further

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

    * [Audit Trail Documentation](https://www.scaleway.com/en/docs/identity-and-access-management/audit-trail/)
    * [Scaleway Slack Community](https://scaleway-community.slack.com/) join the #audit-trail channel
    * [Contact our support team](https://console.scaleway.com/support/tickets).
  version: v1alpha1
servers:
- url: https://api.scaleway.com
components:
  schemas:
    google.protobuf.Struct:
      type: object
      properties:
        <fieldKey>:
          type: object
    scaleway.audit_trail.v1alpha1.Event:
      type: object
      properties:
        id:
          type: string
          description: (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        recorded_at:
          type: string
          description: (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        locality:
          type: string
        principal:
          $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.Event.Principal'
        organization_id:
          type: string
          description: (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        project_id:
          type: string
          description: (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        source_ip:
          type: string
          description: (IP address)
          example: 1.2.3.4
        user_agent:
          type: string
        product_name:
          type: string
        service_name:
          type: string
        method_name:
          type: string
        resource:
          $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.Resource'
        request_id:
          type: string
          description: (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
        request_body:
          $ref: '#/components/schemas/google.protobuf.Struct'
        status_code:
          type: integer
          format: uint32
      x-properties-order:
      - id
      - recorded_at
      - locality
      - principal
      - organization_id
      - project_id
      - source_ip
      - user_agent
      - product_name
      - service_name
      - method_name
      - resource
      - request_id
      - request_body
      - status_code
    scaleway.audit_trail.v1alpha1.Event.Principal:
      type: object
      properties:
        id:
          type: string
          description: (UUID format)
          example: 6170692e-7363-616c-6577-61792e636f6d
      x-properties-order:
      - id
    scaleway.audit_trail.v1alpha1.ListEventsRequest.OrderBy:
      type: string
      enum:
      - recorded_at_desc
      - recorded_at_asc
      default: recorded_at_desc
    scaleway.audit_trail.v1alpha1.ListEventsResponse:
      type: object
      properties:
        events:
          type: array
          description: Single page of events matching the requested criteria.
          items:
            $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.Event'
        next_page_token:
          type: string
          description: Page token to use in following calls to keep listing.
      x-properties-order:
      - events
      - next_page_token
    scaleway.audit_trail.v1alpha1.ListProductsResponse:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.Product'
        total_count:
          type: integer
          format: uint64
      x-properties-order:
      - products
      - total_count
    scaleway.audit_trail.v1alpha1.Product:
      type: object
      properties:
        title:
          type: string
        name:
          type: string
      x-properties-order:
      - title
      - name
    scaleway.audit_trail.v1alpha1.Resource:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.ResourceType'
        created_at:
          type: string
          description: (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        updated_at:
          type: string
          description: (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        deleted_at:
          type: string
          description: (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        name:
          type: string
        secm_secret_info:
          type: object
          properties:
            path:
              type: string
          nullable: true
          x-properties-order:
          - path
          x-one-of: info
        secm_secret_version_info:
          type: object
          properties:
            revision:
              type: integer
              format: uint32
          nullable: true
          x-properties-order:
          - revision
          x-one-of: info
      x-properties-order:
      - id
      - type
      - created_at
      - updated_at
      - deleted_at
      - name
      - secm_secret_info
      - secm_secret_version_info
    scaleway.audit_trail.v1alpha1.ResourceType:
      type: string
      enum:
      - unknown_type
      - secm_secret
      - secm_secret_version
      default: unknown_type
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /audit-trail/v1alpha1/regions/{region}/events:
    get:
      operationId: ListEvents
      summary: List events
      description: Retrieve the list of Audit Trail events for a Scaleway Organization
        and/or Project. You must specify the `organization_id` and optionally, the
        `project_id`.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          description: The region you want to target
          enum:
          - fr-par
          - nl-ams
      - in: query
        name: project_id
        description: (Optional) ID of the Project containing the Audit Trail events.
        schema:
          type: string
          description: (Optional) ID of the Project containing the Audit Trail events.
      - in: query
        name: organization_id
        description: ID of the Organization containing the Audit Trail events.
        required: true
        schema:
          type: string
          description: ID of the Organization containing the Audit Trail events.
      - in: query
        name: resource_type
        description: (Optional) Returns a paginated list of Scaleway resources' features.
        schema:
          type: string
          description: (Optional) Returns a paginated list of Scaleway resources'
            features.
          enum:
          - unknown_type
          - secm_secret
          - secm_secret_version
          default: unknown_type
      - in: query
        name: method_name
        description: (Optional) Name of the method or the API call performed.
        schema:
          type: string
          description: (Optional) Name of the method or the API call performed.
      - in: query
        name: status
        description: (Optional) HTTP status code of the request. Returns either `200`
          if the request was successful or `403` if the permission was denied.
        schema:
          type: integer
          description: (Optional) HTTP status code of the request. Returns either
            `200` if the request was successful or `403` if the permission was denied.
          format: uint32
      - in: query
        name: recorded_after
        description: (Optional) The `recorded_after` parameter defines the earliest
          timestamp from which Audit Trail events are retrieved. Returns `one hour
          ago` by default. (RFC 3339 format)
        schema:
          type: string
          description: (Optional) The `recorded_after` parameter defines the earliest
            timestamp from which Audit Trail events are retrieved. Returns `one hour
            ago` by default. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      - in: query
        name: recorded_before
        description: (Optional) The `recorded_before` parameter defines the latest
          timestamp up to which Audit Trail events are retrieved. Returns `now` by
          default. (RFC 3339 format)
        schema:
          type: string
          description: (Optional) The `recorded_before` parameter defines the latest
            timestamp up to which Audit Trail events are retrieved. Returns `now`
            by default. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      - in: query
        name: order_by
        schema:
          $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.ListEventsRequest.OrderBy'
      - in: query
        name: page_size
        schema:
          type: integer
          format: uint32
      - in: query
        name: page_token
        schema:
          type: string
      - in: query
        name: product_name
        description: (Optional) Name of the Scaleway resource in a hyphenated format.
        schema:
          type: string
          description: (Optional) Name of the Scaleway resource in a hyphenated format.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.ListEventsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/audit-trail/v1alpha1/regions/fr-par/events?organization_id=string"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/audit-trail/v1alpha1/regions/fr-par/events" \
            X-Auth-Token:$SCW_SECRET_KEY \
            organization_id==string
  /audit-trail/v1alpha1/regions/{region}/products:
    get:
      operationId: ListProducts
      summary: Retrieve the list of Scaleway resources for which you have Audit Trail
        events
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          description: The region you want to target
          enum:
          - fr-par
          - nl-ams
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.audit_trail.v1alpha1.ListProductsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/audit-trail/v1alpha1/regions/fr-par/products"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/audit-trail/v1alpha1/regions/fr-par/products" \
            X-Auth-Token:$SCW_SECRET_KEY
