openapi: 3.0.3
info:
  title: OAuth Authorization Code API
  description: |-
    The UPS OAuth Authorization Code API helps integrate UPS services into your business application for providing the service your application grants your customers. For example, you can create UPS shipping labels with shipping rates for merchants from within your application.
    Since your application will not have access to your customer's UPS login credentials, the OAuth authorization code flow is used to let your customer use their UPS credentials, within your application, in a simple and secure way.
    
    The PKCE-enhanced Authorization Code Flow introduces a secret created by the calling application that can be verified by the authorization server; this secret is called the Code Verifier. Additionally, the calling app creates a transform value of the Code Verifier called the Code Challenge 
    and sends this value over HTTPS to retrieve an Authorization Code. This way, a malicious attacker can only intercept the Authorization Code, and they cannot exchange it for a token without the Code Verifier.
    
    Key Business Values:
      - **Enhanced Transaction Security**: The OAuth Authorization Code flow is more secure and reliable since the access token and the refresh token are never exposed in the browser's URL, thus reducing the risk of leakage or theft.
      - **Operational Efficiency**: With the ability to obtain a refresh token when the token expires, your application can maintain a long-term and uninterrupted access to the protected resources, without requiring the user to re-authenticate or re-login.

    Overview of steps in OAuth Authorization Code flow:

    1. When user selects Login, the client application redirects to the authorization server's /authorize endpoint.
    2. The Authorization Server authenticates the user by asking for their login credentials, and after successful login, the authorization server responds back to the application with an authorization code contained within a redirection URI.
    3. The application then sends the authorization code and the redirection URI to the authorization server's /oauth/token endpoint.
    4. The authorization server's /token endpoint verifies the authorization code and the application's client ID contained in the redirect URI, and responds with a with an access token, as well as a refresh token.
    5. The Client application uses the access token to request information from an UPS API.

    Overview of steps in OAuth Authorization Code PKCE flow:
    1. When user selects Login, the client application redirects to the authorization server's /authorize endpoint with Code Challenge
      - **Note:** Prior to redirecting to the authorization server, the application generates and **code_challenge** and **code_verifier** that are related in this way: code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
    2. The Authorization Server authenticates the user by asking for their login credentials, and after successful login, the authorization server responds back to the application with an authorization code contained within a redirection URI.
    4. The application then sends the authorization code , code_verifer and the redirection URI to the authorization server's /oauth/token endpoint.
      - **Note:** When utlizing the PKCE flow, the BASIC Authorization header should **not** be included, just the **client_id** parameter in the body.
    5. The authorization server's /token endpoint verifies the authorization code, code_verifier and the application's client ID contained in the redirect URI, and responds with a with an access token, as well as a refresh token.
    6. The Client application uses the access token to request information from an UPS API.

    - <a href="https://developer.ups.com/api/reference/oauth/authorization-code" target="_blank" rel="noopener">Setting-up OAuth Authorization Code flow</a>
    - <a href="https://github.com/UPS-API/UPS-SDKs" target="_blank" rel="noopener noreferrer">Accelerate API Integration with UPS SDKs</a></br>
    
    </br><p>Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our <a href="https://developer.ups.com/api/reference/postman/guide"
    target="_blank" rel="noopener">Postman Guide</a>. Explore API documentation and sample applications through GitHub.</p>
    <a href="https://god.gw.postman.com/run-collection/29542085-f15285f0-2ffd-4895-b9e4-fcf496f8059a?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D29542085-f15285f0-2ffd-4895-b9e4-fcf496f8059a%26entityType%3Dcollection%26workspaceId%3D7e7595f0-4829-4f9a-aee1-75c126b9d417" target="_blank" rel="noopener noreferrer">
      <img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;"></a>
    <a href="https://github.com/UPS-API" target="_blank" rel="noopener noreferrer">
      <img src="https://www.ups.com/assets/resources/webcontent/images/gitHubButton.svg" alt="Open in GitHub " style="width: 128px; height: 32px;">
    </a>
  version: '1.0'
paths:
  "/v1/oauth/authorize":
    get:
      servers:
        - url: https://wwwcie.ups.com/security
          description: Customer Integration Environment
        - url: https://onlinetools.ups.com/security
          description: Production
      tags:
        - OAuth Auth Code
      summary: Authorize Client
      description: |-
        The Authorize Client endpoint initiates the OAuth Authorization Code flow by redirecting the user to UPS for logging-in and authorize the client application. To begin the authorization flow, the application constructs a URL using the application's client Id, the redirect URI, the scope of permissions requested, and a random string used for subsequent verification. A successful response redirects back to the client with an authorization code that can be exchanged for an access token.
      operationId: AuthorizeClient
      parameters:
      - in: query
        name: client_id
        schema:
          type: string
        description: The public identifier for your application, obtained when you,
          the developer first registered the application.
        required: true
      - in: query
        name: redirect_uri
        schema:
          type: string
        description: URL that tells the authorization server where to send the user
          back to after they approve the request.
        required: true
      - in: query
        name: response_type
        schema:
          type: string
        description: 'Valid Values: code'
        required: true
      - in: query
        name: state
        schema:
          type: string
        description: A random string generated by the application and included in
          the request to prevent CSRF attacks. The application checks that the same
          value is returned after the user authorizes the app.
        required: false
      - in: query
        name: scope
        schema:
          type: string
        description: One or more space-separated strings indicating which permissions
          the application is requesting.
        required: false
      - in: query
        name: code_challenge
        schema:
          type: string
        description: Base64 URL-Encoded SHA256 value of Code Verifier that can be 
          used to verify the code_verifier in the /token step.
        required: false
      responses:
        '302':
          description: successful operation
          headers:
            location:
              description: |-
                The UPS login redirection URI in the following format: https://{UPS_domain_URL}?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}&state={state}&type=ups_com_api

                The value of 'state' will be the same value that the application initially set in the request.
                The 'code' is the authorization code generated by the authorization server.
              schema:
                type: string
            appname:
              description: Name of the application requesting the authorization code.
              schema:
                type: string
            displayname:
              description: Display name of the application requesting the Authorization
                code.
              schema:
                type: string
        '400':
            description: Invalid Request
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '401':
            description: Unauthorized Request
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '403':
            description: Blocked Merchant
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '429':
            description: Rate Limit Exceeded
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
  "/v1/oauth/token":
    post:
      servers:
        - url: https://wwwcie.ups.com/security
          description: Customer Integration Environment
        - url: https://onlinetools.ups.com/security
          description: Production
      tags:
        - OAuth Auth Code
      security:
      - BasicAuthGenerate: []
      description: The Generate Token endpoint exchanges the authorization code received
        from the client application for an access token and a refresh token. The client
        uses the access token to make API requests on behalf of the user by including
        it in the authorization header. The access token will expire after a certain
        period and can be refreshed by using the /refresh endpoint.
      operationId: GenerateToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: 'Valid values: authorization_code'
                  default: authorization_code
                code:
                  type: string
                  description: Authorization code from the UPS login system.
                redirect_uri:
                  type: string
                  description: Callback URL for the requesting application.
                code_verifier:
                  type: string
                  description: |
                    **Only required for PKCE flow**. A randomly generated secret created by the calling application that can be verified by the authorization server.
                client_id:
                  type: string
                  description: |
                    **Only required for PKCE flow**. The public identifier for your application, obtained when you, the developer first registered the application.
              required:
              - grant_type
              - code
              - redirect_uri
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/generateTokenSuccessResponse"
        '400':
            description: Invalid Request
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '401':
            description: Unauthorized Request
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '403':
            description: Blocked Merchant
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '429':
            description: Rate Limit Exceeded
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
  "/v1/oauth/refresh":
    post:
      servers:
        - url: https://wwwcie.ups.com/security
          description: Customer Integration Environment
        - url: https://onlinetools.ups.com/security
          description: Production
      security:
      - BasicAuthRefresh: []
      summary: Refresh Token
      tags:
        - OAuth Auth Code
      operationId: RefreshToken
      description: The /refresh endpoint is used to refresh an expired access token
        in order to continue accessing a UPS API on behalf of a user. The endpoint
        generates a new access/refresh token pair by exchanging a valid refresh token.
        A successful response returns new access and refresh tokens for ongoing API
        access without re-prompting the user.
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  description: 'Valid values: refresh_token'
                  default: refresh_token
                refresh_token:
                  type: string
                  description: Refresh token from GenerateToken operation
              required:
              - grant_type
              - refresh_token
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/refreshTokenSuccessResponse"
        '400':
            description: Invalid Request
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '401':
            description: Unauthorized Request
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '403':
            description: Blocked Merchant
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
        '429':
            description: Rate Limit Exceeded
            content:
                application/json:
                  schema:
                    "$ref": "#/components/schemas/tokenErrorResponse"
components:
  securitySchemes:
    BasicAuthGenerate:
      type: http
      scheme: basic
      description: |
       - **Flow 1: Plain Auth-Code**

       Find your Client ID and Secret on your app info page. 
        1. Select \"Try It\"
        2. In the Security section enter your Client ID as the Username and your Secret as the Password.
        3. Enter any additional information in the Body and Parameters sections.
        4. Select \"Send\" to execute your API request

        - **Flow 2: Auth-Code with PKCE [no http Authorization header required]**
        1. Select \"Try It\"
        2. Include the **client_id** and **code_verifier** parameters in the body of the request. Do not include an Authorization header.
        3. Enter any additional information in the Body and Parameters sections.
        4. Select \"Send\" to execute your API request
    BasicAuthRefresh:
      type: http
      scheme: basic
      description: |
        Find your Client ID and Secret on your app info page. 
        1. Select \"Try It\"
        2. In the Security section enter your Client ID as the Username and your Secret as the Password.
        3. Enter any additional information in the Body and Parameters sections.
        4. Select \"Send\" to execute your API request
  schemas:
    generateTokenSuccessResponse:
      type: object
      properties:
        refresh_token_expires_in:
          description: Expiration time for requested refresh token in seconds.
          type: string
        refresh_token_status:
          description: Status for requested refresh token.
          type: string
        token_type:
          description: Type of requested access token
          type: string
        issued_at:
          description: Issue time of requested token in milliseconds.
          type: string
        client_id:
          description: Client id for requested token.
          type: string
        access_token:
          description: Token to be used in API requests.
          type: string
        refresh_token:
          description: Refresh token to be used in refresh requests when obtaining
            new access token.
          type: string
        scope:
          description: Scope for requested token.
          type: string
        refresh_token_issued_at:
          description: Time that refresh token was issued in milliseconds.
          type: string
        expires_in:
          description: Expire time for requested token in seconds.
          type: string
        refresh_count:
          description: Number of refreshes for requested token.
          type: string
        status:
          description: Status for requested token.
          type: string
    refreshTokenSuccessResponse:
      type: object
      properties:
        refresh_token_expires_in:
          description: Expiration time for requested refresh token in seconds.
          type: string
        refresh_token_status:
          description: Status for requested refresh token.
          type: string
        token_type:
          description: Type for requested token.
          type: string
        issued_at:
          description: Issue time for requested token in milliseconds.
          type: string
        client_id:
          description: Client id for requested token.
          type: string
        access_token:
          description: Token to be used in API requests.
          type: string
        refresh_token:
          description: Token to be used in refresh requests.
          type: string
        scope:
          description: Scope for requested token.
          type: string
        refresh_token_issued_at:
          description: Issue time for requested refresh token in milliseconds.
          type: string
        expires_in:
          description: Expiration time for requested access token in seconds.
          type: string
        refresh_count:
          description: Number of refreshes for requested token.
          type: string
        status:
          description: Status for requested token.
          type: string
    tokenErrorResponse:
      type: object
      properties:
        response:
          "$ref": "#/components/schemas/errorResponseWrapper"
    errorResponseWrapper:
      type: object
      properties:
        errors:
          type: array
          items:
            "$ref": "#/components/schemas/errors"
    errors:
      type: object
      properties:
        code:
          description: Error code
          type: string
        message:
          description: Error message

          type: string