---
swagger: "2.0"
info:
  x-ibm-name: rakbank-customer-sign-in-oauth-api
  title: RAKBANK Customer Sign-in OAuth API
  version: 1.1.0
  contact:
    name: API developer
    email: apideveloper@rakbank.ae
  description: |-
    This API allows the client to generate an OAuth Access Token & Refresh Token after authenticating the customer and taking his/her consent to allow the TPA to operate on this account on his/her behalf.

    Version 1.1.0
    - Makes a call to update Registration Status to 'BLK' - Bank Linkage Success. Client receives token only if this call returns 'Success'.
  name: ""
schemes:
- https
host: sandboxapi.rakbank.ae
basePath: /v1/customer_signin
securityDefinitions:
  clientID:
    description: application's client_id
    in: query
    name: client_id
    type: apiKey
  clientIdHeader:
    in: header
    type: apiKey
    name: X-IBM-Client-Id
  clientSecretHeader:
    in: header
    type: apiKey
    name: X-IBM-Client-Secret
security:
- clientSecretHeader: []
  clientIdHeader: []
- clientID: []
paths:
  /oauth2/authorize:
    get:
      produces:
      - text/html
      summary: endpoint for Authorization Code grant
      description: Redirects to the Bank's Digital Banking Login page. After customer
        has completed authentication and provided consent, the Authorization code
        is redirected to the Third party App's RedirectURI.
      parameters:
      - name: response_type
        in: query
        description: request an authorization code.
        required: true
        type: string
        enum:
        - code
      - name: client_id
        in: query
        description: Third party App's client ID
        required: true
        type: string
      - name: scope
        in: query
        description: Scope being requested
        type: string
        required: true
      - name: redirect_uri
        in: query
        type: string
        description: URI where user is redirected to after authorization. Authorization
          code will be redirected to this URI.
        required: false
      - name: state
        in: query
        type: string
        description: This string will be echoed back to application when user is redirected
        required: false
      - name: account_id
        type: string
        required: true
        in: query
        description: Encrypted Account id of the customer
      - name: uuid
        type: string
        required: true
        in: query
        description: uuid of the customer
      responses:
        302:
          description: |
            Redirect to the clients redirect_uri containing one of the following
            - **authorization code** for Authorization code grant
            - **error** in case of errors, such as the user has denied the request
      security:
      - clientID: []
      operationId: GetAuthorizationCode
    post:
      consumes:
      - application/x-www-form-urlencoded
      produces:
      - text/html
      summary: submit approval to authorization code or access token
      description: |
        Submit resource owners approval (or rejection) for the OAuth2 Server to issue an
        authorization code or access token to the application.
      security: []
      parameters:
      - name: client_id
        in: formData
        description: application requesting the access code or token
        required: true
        type: string
      - name: scope
        in: formData
        description: requested scope of this authorization
        required: true
        type: string
      - name: resource-owner
        in: formData
        description: resource owners user name
        required: true
        type: string
      - name: redirect_uri
        in: formData
        description: URI the application is requesting this code or token to be redirected
          to
        required: true
        type: string
      - name: original-url
        in: formData
        description: URL of the original authorization request
        required: true
        type: string
      - name: dp-state
        in: formData
        description: state information provided in the authorization form
        required: true
        type: string
      - name: dp-data
        in: formData
        description: state information provided in the authorization form
        required: true
        type: string
      responses:
        200:
          description: A consent form for oauth processing.
  /oauth2/token:
    post:
      consumes:
      - application/x-www-form-urlencoded
      produces:
      - application/json
      summary: Request Access Tokens
      description: |
        This endpoint allows requesting an access token following one of the flows below:
        - Authorization Code (exchange code for access token)
        - Refresh Token (exchange refresh token for a new access code)

        The table below indicates the required parameters for each specific grant_type options.
        Empty cells indicate a parameter is ignored for that specific grant type.

        Client authentication:
        - Confidential clients should authenticate using HTTP Basic Authentication. client_id and client_secret must be passed in the Authorization header for Basic Authentication.


        | grant_type           | code       | refresh_token |
        |----------------------|------------|---------------|
        | client_id            | required   | required      |
        | client_secret        | required   | required      |
        | code                 | required   |               |
        | scope                |            | optional      |
        | refresh_token        |            | required      |

        The implicit grant requests, see /oauth2/authorize.
      parameters:
      - name: grant_type
        in: formData
        description: Type of grant
        type: string
        required: true
        enum:
        - authorization_code
        - password
        - client_credentials
        - refresh_token
      - name: code
        in: formData
        description: Authorization code provided by the /oauth2/authorize endpoint
        required: false
        type: string
      - name: scope
        in: formData
        type: string
        description: Scope being requested
        required: false
      - name: refresh_token
        in: formData
        type: string
        description: The refresh token that the client wants to exchange for a new
          access token (refresh_token grant_type)
        required: false
      responses:
        200:
          description: json document containing token, etc.
          schema:
            $ref: '#/definitions/access_token_response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
      security:
      - clientIdHeader: []
        clientSecretHeader: []
  /oauth2/issued:
    get:
      produces:
      - application/json
      summary: Returns list of permission granted to the owner
      description: "This endpoint allows the return of all the issued permission for
        a given authenticated owner per owner authentication \ndefined in the x-ibm-configuration
        section\n"
      responses:
        200:
          description: json document containing issued information, etc.
          schema:
            $ref: '#/definitions/issued_responses'
        401:
          description: failure in retreiving issued list
      security:
      - clientIdHeader: []
        clientSecretHeader: []
    delete:
      consumes:
      - application/x-www-form-urlencoded
      produces:
      - application/json
      summary: Revoke an application/client permission by the authorized owner
      description: Revoke an application/client permission by the authorized owner
      security:
      - clientIdHeader: []
        clientSecretHeader: []
      parameters:
      - name: client-id
        in: query
        description: client-id is the OAuth client_id or application id to be revoked
        required: true
        type: string
      responses:
        200:
          description: OK
  /oauth2/revoke:
    post:
      responses:
        200:
          description: response from revocation
          schema:
            $ref: '#/definitions/token_revoke_response'
      description: |
        This endpoint revokes a given access_token or refresh_token
      parameters:
      - required: true
        type: string
        description: String value of the access_token, or refresh_token to be revoked
        in: formData
        name: token
      - required: true
        type: string
        description: This must contain 'access_token' or 'refresh_token' to indicate
          the token type
        in: formData
        name: token_type_hint
      produces:
      - application/json
      security:
      - clientSecretHeader: []
        clientIdHeader: []
      consumes:
      - application/x-www-form-urlencoded
      summary: Revoke a given access_token or refresh_token
  /oauth2/introspect:
    post:
      consumes:
      - application/x-www-form-urlencoded
      produces:
      - application/json
      summary: Introspect a given access_token supported
      description: |
        This endpoint introspects a given access_token
      security:
      - clientIdHeader: []
        clientSecretHeader: []
      parameters:
      - name: token
        in: formData
        description: String value of the access_token to be introspected
        required: true
        type: string
      - name: token_type_hint
        in: formData
        description: This must contain 'access_token' to indicate the token type
        required: true
        type: string
      responses:
        200:
          description: json document containing access_token information, etc.
          schema:
            $ref: '#/definitions/introspect_response'
        401:
          description: failure
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
  type: oauth
definitions:
  error_response:
    properties:
      status:
        type: string
        description: HTTP Status
        example: "422"
      response_code:
        type: string
        description: API specific error code
        example: "20006"
      property:
        type: string
      response_message:
        type: string
        description: type of the error
        example: business exception
      description:
        type: string
        description: detailed description of the error
        example: beneficiary_id not found
    additionalProperties: false
    required:
    - response_message
    - response_code
    - status
    description: Error Response details
  access_token_response:
    type: object
    additionalProperties: false
    required:
    - token_type
    - access_token
    - expires_in
    - refresh_token
    properties:
      token_type:
        enum:
        - bearer
        description: Token type
      access_token:
        type: string
        description: Access Token
      expires_in:
        type: integer
        description: access_token expires in how many seconds
      scope:
        type: string
        description: scopes allowed for the token
      refresh_token:
        type: string
        description: Refresh Token to be stored against the uuid
      refresh_token_expires_in:
        type: integer
        description: refresh_token expires in how many seconds
      consented_on:
        type: integer
        description: Consented on in Unix time format
      id_token:
        type: string
        description: OIDC token generated as a signed JWT. Returned only when scope
          includes 'openid'.  Details included in the id token - uuid, scope, account_id,
          consented_on
    description: Returns access and refresh tokens and id token when scope includes
      'openid'
  issued_response:
    type: object
    additionalProperties: false
    required:
    - clientId
    - owner
    - scope
    - issuedAt
    - expiredAt
    - refreshTokenIssued
    properties:
      clientId:
        type: string
      clientName:
        type: string
      owner:
        type: string
      scope:
        type: string
      issuedAt:
        type: string
      expiredAt:
        type: string
      refreshTokenIssued:
        type: boolean
      miscInfo:
        type: string
      consentedOn:
        type: string
      appId:
        type: string
      org:
        type: string
      orgId:
        type: string
      provider:
        type: string
      providerId:
        type: string
      catalog:
        type: string
      catalogId:
        type: string
  issued_responses:
    type: array
    items:
      $ref: '#/definitions/issued_response'
  token_revoke_response:
    additionalProperties: false
    type: object
    properties:
      status:
        type: string
  introspect_response:
    type: object
    additionalProperties: false
    required:
    - active
    - client_id
    - client_name
    - username
    - sub
    - exp
    - expstr
    - iat
    - nbf
    - nbfstr
    - scope
    properties:
      active:
        type: boolean
      client_id:
        type: string
      client_name:
        type: string
      username:
        type: string
      sub:
        type: string
      exp:
        type: string
      expstr:
        type: string
      iat:
        type: string
      nbf:
        type: string
      nbfstr:
        type: string
      scope:
        type: string
      miscinfo:
        type: string
      consented_on:
        type: string
      consented_on_str:
        type: string
      grant_type:
        type: string
produces:
- application/json
consumes:
- application/json
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
...