Authentication

OAuth is an open protocol that allows your application to request secure access to private details in a user's PEX account, without their password.

Registering Your Application

To get started, follow these steps:

Register your app by signing up for a developer account on the PEX Developer Portal (https://developer.pexcard.com)

You will receive a unique AppId (also called Client ID) and AppSecret (also called Client Secret) to use in the OAuth flow. You can view the AppId and AppSecret by clicking the lock icon in the portal to reveal their values. Do not share your AppSecret with anyone.

The OAuth Flow

PEX uses the standard OAuth flow to grant access tokens to users. For more information about the OAuth grant flow, see the OAuth documentation (https://tools.ietf.org/html/rfc6749#section-4.1)



Step 1: Connection Request

A user requests to connect your application to PEX. This request is typically triggered by the user clicking a button within your app. Once the user clicks this button, the OAuth flow is triggered.

Step 2: Partner Authentication

You must authenticate your app with PEX. Your application should submit your App credentials to the PEX OAuth Service in order to continue the authorization flow.

Authentication Request:

Method: POST
URL: https://oauth.pexcard.com/Auth/Partner
Headers: Content-Type: application/json
Body:
{

"AppId": "de12abc3",
"AppSecret": "ab1234c45a67a8fd662efd879063e9e",
"ServerCallbackUrl": "https://www.myappurl.com/pexconnectorcallback",
"BrowserClosingUrl": "https://www.myappurl.com/welcome"
}

Description of Fields:

AppId: This is the Client ID received when your app was registered in the PEX Developer portal. To find the AppID, log into the portal and click on the lock icon to reveal the value.
AppSecret: This is the Client Secret you received when you registered your app in the PEX Developer portal. Click on the key to reveal the value. Do not share your Client Secret with anyone.
ServerCallbackUrl: This is the endpoint to which PEX will post the token granted to the end user. For details on how the token will be posted to this URL, see details below.
BrowserClosingUrl: After completing authentication, the user will be redirected to this URL in order to use the connected applications. This URL is based within your app.

Authentication Response:

Status Codes

200: Indicates that your app is authorized

400 or 401: Indicates that your app is not authorized

Body: { "OAuthUrl": "https://oauth.pexcard.com/Home/Auth?sessionid=123-abc-456-def-789" }

Response Description
OAuthUrl: Users should be redirected here to authenticate their PEX credentials.
*NOTE: This URL is valid for only 1 hour after it is issued by the PEX OAuth servers.

Step 3: User Redirect

Upon receiving the response from the PEX OAuth server, your app should redirect the user to the URL returned in the Authentication Response “OAuthUrl” field.

Step 4: Authentication and Authorization

Once the user is redirected to the PEX OAuth URL, PEX will present the user with a login form prompting them to relay their PEX credentials. Upon entering their credentials, PEX will authenticate the user, and determine what features they are authorizing your application to access.



The user must explicitly allow your application access to the listed features in order for PEX to provision a token to your app.

Step 5: Access Token

Once the user is successfully authenticated, and the user has authorized your app to have the features that your plan allows, PEX will send a token to your app and redirect the user to the requested URL.

Access Token Callback:

Method: POST
URL: Provided by the app in the Authentication Request Message (ServerCallbackUrl).
Headers: ContentType: application/json
Body:
{
"Token": "ad12abb4e2034c3aa77f093433b6b61c"
}

Step 6: User Redirect

PEX will redirect the user to the URL provided in the Authentication Request Message (BrowserClosingUrl). This redirect will occur whether or not the user grants access to your app.

Once you have received a token from the PEX OAuth flow, you can use this token to access resources on behalf of your user. For further details on what calls are available, see the documentation on the PEX Developer Portal (https://developer.pexcard.com).

Revoking Tokens

The PEX OAuth server also supports revoking tokens. If your app needs to revoke a token, you can use the following endpoint:

Method: POST
URL: https://oauth.pexcard.com/Auth/Token/Revoke
Headers: Content-Type: application/json
Body:
{
"AppId": "de16bdc8",
"AppSecret": "ac9893c50a93a2ded662efd879063e9e",
"Token": "ef21acc9e2034c3aa77f093433b6b61c"
}

Description of Fields:

AppId: This is the Client ID received when your app was registered in the PEX Developer portal. To find the AppID, log into the portal and click on the lock icon to reveal the value.
AppSecret: This is the Client Secret received when your app was registered in the PEX Developer portal. Click on the key to reveal the value. Do not share your Client Secret with anyone.
Token: This is the token you would like to revoke. This should be the token that was sent to your app by PEX as part of the OAuth Flow.

Response:
Status Codes:
200: Token has been revoked
400 or 401: Token was not revoked

Security Considerations for Connecting to PEX

  • Storing Application Credentials:
    Your application credentials uniquely identify your application to PEX. You must protect these credentials. You should only allow a limited number of your developers access to the PEX developer portal. This should be a select group that requires to the credentials. Although the Client ID may be shared freely, your Client Secret should be closely guarded. Never embed your Client Secret within a distributed application (such as a mobile app), and never send it to your users’ browsers (ex: client-side javascript).
  • Storing User Tokens: Tokens securely authenticate your access on behalf of a PEX user. The tokens must be stored in an encrypted manner on your servers. Never embed these tokens in either a distributed app (such as a mobile app) or client-side javascript.
  • Secure Data Exchange: PEX URLs will always be protected via SSL. Similarly, your app should only expose URLs via SSL. The certificates on your app must be valid, or PEX will not be able to send data to your app.

Common problems

  • Username / password mismatch: Is the User Name/Password combination you are using from Sandbox or Production? A production user name/password combination won't work in sandbox and vice versa.
  • General authentication error: Is your application using TLS 1.2? PEX depricated support for TLS 1.0 in early 2018.