VeevaID

VeevaID provides single sign-on and digital identity across all Veeva clinical sponsor and partner applications. With VeevaID, clinical research sites can easily access systems across multiple sponsors and studies for increased efficiency and speed.

VeevaID is an identity provider that provides authentication using the OAuth 2.0 Authorization Code Flow with Proof Key for Code Exchange (PKCE). The VeevaID API allows partners to authenticate users using their VeevaID credentials.

Users must first register for a VeevaID and then interact with your application.

Integrating with VeevaID

The VeevaID API allows partners to integrate with VeevaID. By integrating with VeevaID, site personnel can log in to all Veeva partner applications with no additional username or password required.

Step 1: Register Your Application

Register your application with Veeva. To register, you must email productpartner@veeva.com with the information specified below.

Once provided, Veeva will provide you with a client_id which you will use to make API calls.

In your registration request email, use the subject VeevaID Partner Program | Application Name and include the following information:

Name	Type	Description
`app_name`	Text (256)	Your Application Name, used for branding the VeevaID login screen. For example:
`app_png_logo_url`	Text (1024)	The URL of your application logo in PNG format, for use on Veeva’s partners website. Max width: 300 px.
`app_short_description`	Text (256)	A short description of your application for use on Veeva’s partners website.
`app_home_url`	Text (1024)	The URL to send users to when they click your logo on Veeva’s partners website.
`oauth_redirect_urls`	Text (1024)	Tells the authorization server where to send the user after they approve the request. This is where the user lands after clicking Quick entry with VeevaID. The redirect URL must be an exact match – regular expression schemes are not allowed.

Step 2: Authorization

We'll be using the Authorization Code Grant Flow, suitable for web applications running on the server-side, as well as with mobile and client-side applications (using the PKCE extension).

GEThttps://id.veeva.com/auth/authorize

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

Query Parameters

Name	Description
`client_id`	The unique identifier for your application which grants access to the VeevaID APIs; obtained once Veeva approves your registration request.
`response_type`	Value must be `code`. This tells the VeevaID authorization server that the application is initiating OAuth’s Authorization Code Grant Flow.
`code_challenge`	Hashed value of the `code_verification` with code challenge method. For more information, refer to OAuth’s PKCE extension documentation.
`code_challenge_method`	Value must be `S256`, indicating a Base64URL encoded SHA-256 hash will be applied on the code verifier.
`scope`	Value must be `vidauth`. This value is defined by Veeva and indicates which permissions the application is requesting.
`redirect_uri`	Application callback URL receiving the authorization code. Must be strictly matched with `redirect_url` registered in the application client. Query parameters are not allowed.
`state`	A unique, randomly generated, opaque, and non-guessable String generated by your application and sent when starting this authentication request. Your application should then check that the same value is returned from the authorization server. This is critical to prevent cross-site request forgery attacks (CSRF).

Example Request

The URL should be constructed dynamically:

curl -X GET id.veeva.com/auth/authorize?
  client_id=”YOUR_APP_ID”
  &response_type=code
  &redirect_uri=https%3A%2F%2Fexample.org%2Fcallback
  &scope=vidauth
  &state=xcoiv98y2kd22vusuye3kch
  &code_challenge=xxxxT8X2jffuTgXg8IVy5sAzjw-8C3a4RC1xGoaWCAY
  &code_challenge_method=S256

Step 3: Generate User Access Token

After the user has authorized your application, you will receive a code. The next step is to exchange that code for a user access token. This request is typically invoked from the server-side.

POSThttps://id.veeva.com/auth/token

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

Query Parameters

Name	Description
`grant_type`	Value must be `authorization_code`.
`code`	The authorization code value received from the `/authorize` Authorization request.
`client_id`	he unique identifier for your application which grants access to the VeevaID APIs; obtained once Veeva approves your registration request.
`redirect_uri`	Must be the same redirect URL which was passed to the `/authorize` Authorization request.
`code_verifier`	The code verifier for this PKCE request, which your application generated before the `/authorization` Authorization request.

Example Request

curl -X POST id.veeva.com/auth/token?
grant_type= "authorization_code"
&code= "xxxxpcdC3J68Q-MbSRLu18un5bnKOxhIETCz7inxPw8"
&redirect_uri= "https%3A%2F%2Fexample.org%2Fcallback"
&code_verifier= "xxxxE94-9n_bS_ygjh0mCj0neTeI-rK3rIguAFhDIsw"
&client_id= "YOUR_APP_ID"

Example Response

{
    "access_token":"XXxXFkS4tmvI_cEkn3Pm5JFylE7arbYWGbj0P3WwOaU",
    "token_type":"Bearer",
    "expires_in":1800
}

Step 4: Retrieve User Info

Once your application has a valid access token, you can introspect the user information.

GEThttps://id.veeva.com/auth/user_info

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`

Example Request

curl GET -H "Authorization: Bearer xxxxng5AHN5E3yn4IptXFKP7xzVTtnrZq87l50t4blI" 
https://id.veeva.com/auth/user_info

Example Response

{
 "sub": "1437275311",
  "primary_email": "bill.bokey@veepharm.com",
  "language": "en",
  "vuid": 1437275311,
  "first_name": "Bill",
  "last_name": "Bokey",
  "phone_code": "33",
  "phone_number": "6503043535",
  "secondary_email": ""
}

Response Details

The JSON response contains information about the user. For example, sub (subject) is the user’s VeevaID.