OAuth 2.0

FedEx Supply Chain APIs support the OAuth 2.0 protocol to authorize the external applications to call the APIs. Third-party applications need to implement the OAuth 2.0 flow in order to get secure delegated access to merchant’s data on behalf of their users.
Before you begin with OAuth 2.0 integration, you need to register an app in FedEx Supply Chain API Developer Portal by logging in with your credentials. As part of app registration, you must provide the basic registration information like application name, organization name, redirect URI (HTTPS and protected by TLS), etc. Once the app is registered, it will be assigned a unique client ID and client secret that will be used in the OAuth 2.0 flow. The client secret is only visible upon creation of the client application or when you reset the client secret.

Client – Any third-party application that would like access to a merchant’s data that resides in the Fulfillment Platform. A user must grant permission before the client can access any data.

Resource Server API – The API server that accesses the merchant’s data.

Authorization Server – The server that presents the FedEx® Fulfillment login user interface so that the user can approve or deny the access.

User (“Resource Owner”) – A FedEx Fulfillment platform account user. User belongs to a merchant (also called a retailer). This is the account that gives permission to a client to access the merchant’s data via Fulfillment API.

Client ID – After you register your app in FedEx Supply Chain API Developer Portal, you will receive a client ID and client secret. The client ID is considered as public information. It is the unique shared secret for your client application.

Client Secret – The client secret MUST be kept as secret. In the OAuth2, the client secret is used as a mean of authorizing a client. This secret proves to the authentication server that the client app is authorized to make a request on behalf of the user. The client secret can be retrieved from your API Developer Portal.

Redirect URL – The location to redirect the user after the authorization is granted. The redirect URI must be identical to the redirect URL specified in your Fulfillment Platform Developer Portal.

State– A query parameter that the client includes in the request that is sent to the Authorization Server which returns as a parameter of the response unmodified. This field is optional but allows for additional protection from Cross Site Request Forgery.

Scope – An optional parameter consisting of one or more scope values to indicate which part of the merchant’s data you wish to access.

Access Token - If the user authorizes your client’s request for access, FedEx Supply Chain API Developer Portal will return an access token, which is used to sign each API requests. The access token typically expires in 1 hour.

Refresh Token – Along with the access token, the refresh token will be returned to you when the user authorizes your client’s request for access. The refresh token expires in 31 days (2682000 seconds). The maximum number of times a refresh token can be requested is set to 4096 per application on API Developer Portal. Once the refresh token use count exceeds the limit, the application has to re-authorize the user to get a new access token and refresh token.

FedEx Supply Chain uses the OAuth 2.0 authorization code grant flow to issue the access token on behalf of users. Client application invokes FedEx Supply Chain OAuth 2.0 Authorization endpoint, which brings the FedEx Fulfillment Login page to the user. User enters his/her FedEx Fulfillment user name and password and clicks the Login button. If the authentication is successful, the user is redirected to the authorization screen with the “Allow access” and “No thanks” options. After the user approves the access, the access token is generated with appropriate access depending on the scope. This access token will be sent through HTTP Authorization Header on every API request.

Swagger

																												
swagger: "2.0"
info:
  x-ibm-name: oauth-20
  title: OAuth 2.0
  version: 1.0.0
  description: ""
schemes:
- https
basePath: /fsc
securityDefinitions:
  clientID:
    description: The client ID you received when you first registered an app in FedEx
      Supply Chain API Developer Portal.
    in: query
    name: client_id
    type: apiKey
security:
- clientID: []
paths:
  /oauth2/authorize:
    get:
      produces:
      - text/html
      summary: FedEx Supply Chain OAuth 2.0 Authorization endpoint, which brings the
        FedEx Fulfillment Login page to the user
      description: description
      parameters:
      - name: response_type
        in: query
        description: The response_type has to be “code” to indicate to the Authorization
          Server to receive the authorization code.
        required: true
        type: string
        enum:
        - code
        - token
      - name: scope
        in: query
        description: 'One or more scope values to indicate which part of user’s account
          data you want to access. E.g: Fulfillment_Returns'
        type: string
        required: false
      - name: redirect_uri
        in: query
        type: string
        description: Indicates the URI to return the user to after authorization is
          complete.
        required: true
      - name: state
        in: query
        type: string
        description: A unique ID generated by your application that you can verify
          later. This will be returned by Authorization Server unmodified.
        required: false
      - name: org_name
        type: string
        required: true
        in: query
        description: Partner or organization name.
      responses:
        200:
          description: An HTML form for authentication or authorization of this request.
        302:
          description: Redirect to the clients redirect_uri
      security:
      - clientID: []
    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: The client ID you received when you first registered an app in
          FedEx Supply Chain API Developer Portal.
        required: true
        type: string
      - name: scope
        in: formData
        description: 'One or more scope values to indicate which part of user’s account
          data you want to access. E.g: Fulfillment_Returns'
        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
      responses:
        200:
          description: Cool
  /oauth2/token:
    post:
      summary: Request Access Tokens and Refresh Token
      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)
      security: []
      parameters:
      - name: grant_type
        in: formData
        description: "Indicates the grant type for the API call. Valid Values:  •\t“authorization_code”:
          this is used to retrieve the initial access token. The code parameter must
          be passed with the authorization code retrieved from the authorize API call.
          •\t“refresh_token”: this is used to refresh the access token.  The code
          parameter must be passed with the refresh_token value from the initial token
          API call."
        type: string
        required: true
        enum:
        - authorization_code
        - password
        - client_credentials
        - refresh_token
      - name: client_id
        in: formData
        description: The client ID you received when you first registered an app in
          FedEx Supply Chain API Developer Portal.
        required: true
        type: string
      - name: client_secret
        in: formData
        description: The client secret you received when you first registered an app
          in Fulfillment Platform Developer Portal.
        required: true
        type: string
      - name: code
        in: formData
        description: The code is either the value of the authorization code or the
          refresh token, depending on the grant_type.
        required: false
        type: string
      - name: redirect_uri
        in: formData
        description: Indicates the URI to return the user to after authorization is
          complete.
        required: false
        type: string
      - name: username
        in: formData
        type: string
        description: Resource owner username
        required: false
      - name: password
        in: formData
        type: string
        description: Resource owner password
        required: false
      - name: scope
        in: formData
        type: string
        description: 'One or more scope values to indicate which part of user’s account
          data you want to access. If it is provided, the default is used based on
          the settings in your Developer Portal. NOTE: The scope is space delimited
          list of scope values. Default scope FulFillment_Returns'
        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
      - name: org_name
        type: string
        required: true
        in: header
        description: Partner or organization name.
      responses:
        200:
          description: json document containing token, etc.
          schema:
            $ref: '#/definitions/access_token_response'
        400:
          description: json document that may contain additional details about the
            failure
      produces:
      - application/json
      - text/json
      consumes:
      - application/x-www-form-urlencoded
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
  type: oauth
definitions:
  access_token_response:
    type: object
    additionalProperties: false
    required:
    - token_type
    - access_token
    - expires_in
    properties:
      token_type:
        enum:
        - bearer
      access_token:
        type: string
      expires_in:
        type: integer
      scope:
        type: string
      refresh_token:
        type: string
produces:
- application/json