swagger: '2.0'
info:
  version: 2.0.1
  title: Alvaria&trade; Cloud Authorization (OAuth 2.0)
  contact:
    name: Alvaria Software
    url: 'https://www.alvaria.com'
  description: |-
    ## Overview
    The endpoint for authentication is:
    ```
    https://{FQDN}/tokenservice/oauth2/access_token?realm={orgId}
    ```
    - __`orgId`__ is your organization name as supplied by Alvaria.    
    - See __Table 1__ below for __`FQDN`__ details
    
    __Table 1__: List of FQDN for every cloud provider and region  
    | **Cloud Vendor**  | **Region** | **FQDN** |
    | --- | --- | --- |
    | Amazon Web Service (AWS) | United States | https://myaspect.id.aspect-cloud.net |
    | Amazon Web Service (AWS) | Europe | https://myaspect.eu.id.aspect-cloud.net |
    | Amazon Web Service (AWS) | United Kingdom | https://myaspect.uk.id.aspect-cloud.net |
    | Amazon Web Service (AWS) | Canada | https://myaspect.yyz.id.aspect-cloud.net |
    | Microsoft Azure | United States | https://myaspect.us-a.id.aspect-cloud.net |
    | GCP | United States | https://myaccount.dsm.sre.alvaria.cloud |    
  
    The following provides an example in [__curl__](https://curl.haxx.se/) of how to request an oauth token using the authentication endpoint.
    ```
    curl -X "POST" "https://myaspect.id.aspect-cloud.net/tokenservice/oauth2/access_token" \
    -H "content-type: application/x-www-form-urlencoded" \
    -u "myAppName:ac0002ebdacc90f5a61ab99b703cb693" \
    --data-urlencode "realm=myOrganization" \
    --data-urlencode "scope=provisioningapi engagementcenterapi streamingapi" \
    --data-urlencode "grant_type=client_credentials"
    ```
  
    where:
      - __`clientId:secret`__ are values supplied by Alvaria as a result of registering the application with Alvaria&trade; Cloud. In the previous example, the client Id is __myAppName__ and the secret is __ac0002ebdacc90f5a61ab99b703cb693__.
      - __`scope`__ must be supplied to indicate which APIs the client needs authorization to access.  In the example the client is asking for permission to access the provisioning, reporting and campaign APIs.
      - __`grant_type`__ must be set to __client_credentials__.  The grant_type provides the context for the username value passed in the authorization request.  Specifically, that the username is to be interpreted as the clientId and secret.
    
    You can try out the authorization request in tools such as Postman by importing the [__authorization swagger file__](/OpenApiFiles/ViaAuthDeprecatedExternalSwagger.yaml) into the Postman app.
  
    A successful request returns an oauth token that must be supplied in all future REST API calls.  The value of the oauth token is returned in the "access_token" property of a successful response.
    ```
    {
      "access_token": "ad97f5cb-08b6-4072-99a7-d434d251c962",
      "scope": "provisioningapi engagementcenterapi streamingapi",
      "token_type": "Bearer",
      "expires_in": 3599
    }
    ```
    By default all tokens expire in 60 minutes as indicated in the "expires_in" property (expressed in seconds) returned from the authentication call.  Applications must reissue the original authentication call to get a new token before the expiration time elapses.

host: myaspect.id.aspect-cloud.net
schemes:
  - https
consumes:
  - application/x-www-form-urlencoded
produces:
  - application/json
paths:
  /tokenservice/oauth2/access_token:
    post:
      tags:
        - accessToken
      operationId: getAccessToken
      summary: Get oauth token
      parameters:
        - name: realm
          in: query
          description: organization to request an oauth token for
          required: true
          type: string
        - name: scope
          in: formData
          type: string
          required: true
          description: api permissions requested
        - name: grant_type
          in: formData
          type: string
          required: true
          description: token request type
          default: client_credentials
      responses:
        '200':
          schema:
            $ref: '#/definitions/TokenResponse'
          description: Successful response
        '400':
          schema:
            $ref: '#/definitions/ErrorResponse'
          description: Bad Request
        '401':
          description: Unauthorized
        '405':
          schema:
            $ref: '#/definitions/ErrorResponse'
          description: Method Not Allowed
        '408':
          schema:
            $ref: '#/definitions/ErrorResponse'
          description: Request Timeout
        '429':
          schema:
            $ref: '#/definitions/ErrorResponse'
          description: Throttled
        '500':
          schema:
            $ref: '#/definitions/ErrorResponse'
          description: Internal Server Error
      security:
        - basicAuth: []
securityDefinitions:
  basicAuth:
    type: basic
definitions:
  TokenResponse:
    type: object
    properties:
      access_token:
        type: string
        example: 76f22112-76f8-482b-a685-139b98029986
      scope:
        type: string
        example: engagementcenterapi streamingapi
      token_type:
        type: string
        default: Bearer
        example: Bearer
      expires_in:
        type: integer
        example: 3599
  ErrorResponse:
    type: object
    properties:
      code:
        type: integer
        description: Error code
      message:
        type: string
        description: Error message.
