swagger: '2.0'
host: 'orgId.domain'
schemes:
  - https
info:
  version: "3.1"
  title: Alvaria Cloud&reg; Authorization REST API
  contact:
    name: Alvaria
    url: 'https://www.alvaria.com'
    email: support@alvaria.com
  license:
    name: 'License: Creative Commons Attribution 4.0 International Public License'
    url: 'https://creativecommons.org/licenses/by/4.0/legalcode'
  description: |-
    ## Overview

      The Alvaria Cloud&reg; MyAccount Authorization & Authentication REST APIs enable developers to get access
      to other available APIs.
    
      Information on Dynamic Client Registration can be found in [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) and [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592)
    
      __Note__: The domain in the base URL corresponds to the Alvaria&trade; website that hosts the API. Presently, it differs by cloud vendor.
    
      __Table 1__: base URLs for each cloud solution
      | **Cloud Vendor**  | **Domain** |
      | --- | --- |
      | Amazon Web Service (AWS) | via.aspect-cloud.net |
      | Microsoft Azure | via.aspect-cloud.net |
      | GCP | apc.alvaria.cloud |
paths:
  '/via/v1/organizations/{orgId}/oauth/clients':
    parameters:
      - $ref: '#/parameters/orgId'
    get:
      tags:
        - OAuth2 Clients
      operationId: getOAuthClientList
      summary: Get list of OAuthClient metadata
      description: |
        Get list of OAuthClient metadata, Response will NOT contain client_secret.
      produces:
        - application/json
      security:
        - oauth:
            - myaccount.clients.list
          apiKey: []
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/ListOAuthClientResponseMinusSecret'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource Not Found
        '405':
          description: Method Not Allowed
        '429':
          description: Throttled
        '500':
          description: Internal server error
    post:
      tags:
        - OAuth2 Clients
      operationId: generateNewOAuthClient
      summary: Generates a new OAuthClient
      description: Generates a new OAuthClient
      consumes:
        - application/json
      produces:
        - application/json
      security:
        - oauth:
            - myaccount.clients.create
          apiKey: []
      parameters:
        - $ref: '#/parameters/CreateOAuthClientRequest'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/OAuthClientResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource Not Found
        '405':
          description: Method Not Allowed
        '429':
          description: Throttled
        '500':
          description: Internal server error
  '/via/v1/organizations/{orgId}/oauth/clients/{clientId}':
    parameters:
      - $ref: '#/parameters/orgId'
      - $ref: '#/parameters/clientId'
    get:
      tags:
        - OAuth2 Clients
      operationId: getOAuthClient
      summary: Get an OAuthClient metadata
      description: Get an OAuthClient metadata, Response will NOT contain client_secret.
      produces:
        - application/json
      security:
        - oauth:
            - myaccount.clients.view
          apiKey: []
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/OAuthClientResponseMinusSecret'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource Not Found
        '405':
          description: Method Not Allowed
        '429':
          description: Throttled
        '500':
          description: Internal server error
    put:
      tags:
        - OAuth2 Clients
      operationId: updateOAuthClient
      summary: Update an OAuthClient metadata
      description: Update an OAuthClient metadata, Response will NOT contain client_secret.
      consumes:
        - application/json
      produces:
        - application/json
      security:
        - oauth:
            - myaccount.clients.modify
          apiKey: []
      parameters:
        - $ref: '#/parameters/CreateOAuthClientRequest'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/OAuthClientResponseMinusSecret'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource Not Found
        '405':
          description: Method Not Allowed
        '429':
          description: Throttled
        '500':
          description: Internal server error
    delete:
      tags:
        - OAuth2 Clients
      operationId: deleteOAuthClient
      summary: Delete an OAuthClient
      description: Delete an OAuthClient metadata.
      security:
        - oauth:
            - myaccount.clients.delete
          apiKey: []
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource Not Found
        '405':
          description: Method Not Allowed
        '429':
          description: Throttled
        '500':
          description: Internal server error
parameters:
  orgId:
    name: orgId
    in: path
    description: Name of a customer organization.
    required: true
    type: string
  clientId:
    name: clientId
    in: path
    description: Identifier of an OAuthClient.
    required: true
    type: string
  CreateOAuthClientRequest:
    in: body
    name: createOAuthClientRequest
    description: OAuth Client request model as defined here [https://datatracker.ietf.org/doc/html/rfc7591]
    required: true
    schema:
      $ref: '#/definitions/OAuthClientRequest'
securityDefinitions:
  apiKey:
    type: apiKey
    in: header
    name: x-api-key
  oauth:
    type: oauth2
    description: |-
      Oauth2 security definition describing client credentials grant. The `tokenUrl` should be modified in the generated client code to match your region and organization name

      - Replace `tokenHost` with your actual host where MyAccount service is hosted.
      - Replace `orgId` with your organization's alias.
      
      __Table 2__: access_token endpoints for each region
      | **Cloud Vendor**  | **Region** | **tokenHost** |
      | --- | --- | --- |
      | Amazon Web Service (AWS) | US | myaspect.id.aspect-cloud.net |
      | Amazon Web Service (AWS) | Europe | myaspect.eu.id.aspect-cloud.net |
      | Amazon Web Service (AWS) | UK | myaspect.uk.id.aspect-cloud.net |
      | Amazon Web Service (AWS) | Canada | myaspect.ca.id.aspect-cloud.net |
      | Microsoft Azure | US | myaspect.us-a.id.aspect-cloud.net |
      | GCP | DSM | myaccount.dsm.sre.alvaria.cloud |
    tokenUrl: 'https://tokenHost/tokenservice/oauth2/access_token?realm=orgId'
    flow: application
    scopes:
      myaccount.clients.list: Retrieve a list of OAuthClient resources
      myaccount.clients.create: Create OAuthClient resource
      myaccount.clients.modify: Update OAuthClient resource
      myaccount.clients.view: Retrieve OAuthClient resource
      myaccount.clients.delete: Delete OAuthClient resource
definitions:
  OAuthClientRequest:
    type: object
    required:
      - scope
    properties:
      redirect_uris:
        type: array
        description: >-
          Array of redirection URI strings for use in redirect-based flows
          such as the authorization code flow.
        items:
          type: string
        example: [ "https://client.example.org/callback", "https://client.example.org/callback2" ]
      grant_types:
        type: array
        description: >-
          Array of OAuth 2.0 grant type strings that the client can use at
          the token endpoint.
        items:
          type: string
        example: [ authorization_code, client_credentials, refresh_token ]
      response_types:
        type: array
        description: >-
          Array of the OAuth 2.0 response type strings that the client can
          use at the authorization endpoint.
        items:
          type: string
        example: [ code, id_token ]
      client_name:
        description: Human-readable string name of the client
        type: string
        example: CUSTOMER_ORG_API_CLIENT
      scope:
        description: String containing a space-separated list of OAuth 2.0 scope values
        type: string
        example: myaspect.users myaspect.teams myaspect.teams.write
      client_description:
        description: Human Readable Description of a client.
        type: string
        example: Fully-Authorized Client
      contacts:
        description: Array of the OAuth 2.0 response type strings representing ways to contact people responsible for this client, typically email addresses.
        type: array
        items:
          type: string
        example: [ name1@company1.com, name2@company2.com ]
  OAuthClientResponse:
    title: OAuthClientResponse
    type: object
    description: OAuth Client as defined here [https://datatracker.ietf.org/doc/html/rfc7591]
    properties:
      client_id:
        type: string
        description: Client identifier, Server-generated identifier for the OAuth client. This cannot be changed.
        example: 2DxowL00RyG6OZdbYNaQs3R
      client_secret:
        type: string
        description: Client secret, will only be displayed once, and only upon client creation and new secret generation
        example: P9dvyTNFyI7RCaRRmRp3E3FR0WV0jSUDMAo
      client_id_issued_at:
        description: |
          Time, in ticks, at which the client was issued. The
          time is represented as the number of seconds from
          1970-01-01T00:00:00Z as measured in UTC until the date/time of
          issuance.
        type: number
        example: 1659104786
      client_secret_expires_at:
        description: |
          Time, in ticks, at which the client identifier will expire.
          The time is represented as the number of seconds from
          1970-01-01T00:00:00Z as measured in UTC until the date/time of
          expiry.
          0 means that it will never expire.
        type: number
        example: 0
      redirect_uris:
        type: array
        description: >-
          Array of redirection URI strings for use in redirect-based flows
          such as the authorization code flow.
        items:
          type: string
        example: [ "https://client.example.org/callback", "https://client.example.org/callback2" ]
      registration_client_uri:
        type: string
        description: >-
          String containing the fully qualified URL of the client
          configuration endpoint for this client.
        example: https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R
      grant_types:
        type: array
        description: >-
          Array of OAuth 2.0 grant type strings that the client can use at
          the token endpoint.
        items:
          type: string
        example: [ authorization_code, client_credentials, refresh_token ]
      response_types:
        type: array
        description: >-
          Array of the OAuth 2.0 response type strings that the client can
          use at the authorization endpoint.
        items:
          type: string
        example: [ code, id_token ]
      client_name:
        description: Human-readable string name of the client
        type: string
        example: CUSTOMER_ORG_API_CLIENT
      scope:
        description: String containing a space-separated list of OAuth 2.0 scope values
        type: string
        example: myaspect.users myaspect.teams myaspect.teams.write
      x_api_key:
        description: Alvaria&trade; generated x_api_key (x-api-key), used for API access tracking
        type: string
        example: 7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39
      client_description:
        description: Human Readable Description of a client.
        type: string
        example: Fully-Authorized Client
      contacts:
        description: Array of the OAuth 2.0 response type strings representing ways to contact people responsible for this client, typically email addresses.
        type: array
        items:
          type: string
        example: [name1@company1.com, name2@company2.com]
  ListOAuthClientResponseMinusSecret:
    type: array
    items:
      $ref: '#/definitions/OAuthClientResponseMinusSecret'
  OAuthClientResponseMinusSecret:
    title: OAuthClientResponseMinusSecret
    type: object
    description: OAuth Client as defined here [https://datatracker.ietf.org/doc/html/rfc7591]
    properties:
      client_id:
        type: string
        description: Client identifier, Server-generated identifier for the OAuth client. This cannot be changed.
        example: 2DxowL00RyG6OZdbYNaQs3R
      client_id_issued_at:
        description: |
          Time, in ticks, at which the client was issued. The
          time is represented as the number of seconds from
          1970-01-01T00:00:00Z as measured in UTC until the date/time of
          issuance.
        type: number
        example: 1659104786
      client_secret_expires_at:
        description: |
          Time, in ticks, at which the client identifier will expire.
          The time is represented as the number of seconds from
          1970-01-01T00:00:00Z as measured in UTC until the date/time of
          expiry.
          0 means that it will never expire.
        type: number
        example: 0
      redirect_uris:
        type: array
        description: >-
          Array of redirection URI strings for use in redirect-based flows
          such as the authorization code flow.
        items:
          type: string
        example: [ "https://client.example.org/callback", "https://client.example.org/callback2" ]
      registration_client_uri:
        type: string
        description: >-
          String containing the fully qualified URL of the client
          configuration endpoint for this client.
        example: https://server.example.com/via/v1/organizations/myorg/oauth/clients/2DxowL00RyG6OZdbYNaQs3R
      grant_types:
        type: array
        description: >-
          Array of OAuth 2.0 grant type strings that the client can use at
          the token endpoint.
        items:
          type: string
        example: [ authorization_code, client_credentials, refresh_token ]
      response_types:
        type: array
        description: >-
          Array of the OAuth 2.0 response type strings that the client can
          use at the authorization endpoint.
        items:
          type: string
        example: [ code, id_token ]
      client_name:
        description: Human-readable string name of the client
        type: string
        example: CUSTOMER_ORG_API_CLIENT
      scope:
        description: String containing a space-separated list of OAuth 2.0 scope values
        type: string
        example: myaspect.users myaspect.teams myaspect.teams.write
      x_api_key:
        description: Alvaria&trade; generated x_api_key (x-api-key), used for API access tracking
        type: string
        example: 7FFAC9BB21628320FAEBC5786F152B0F2309D6528C7284B5E3E34E1AFE204A39
      client_description:
        description: Human Readable Description of a client.
        type: string
        example: Fully-Authorized Client
      contacts:
        description: Array of the OAuth 2.0 response type strings representing ways to contact people responsible for this client, typically email addresses.
        type: array
        items:
          type: string
        example: [ name1@company1.com, name2@company2.com ]
tags:
  - name: OAuth2 Clients
    description: |
      Operations Relating Dynamic Client Registration Management, as defined in: [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) & [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592)