Authentication

GET /auth/authorize

Requesting An Authorization Code

To begin, submit a client side GET request to the authorize action. The following parameters are required:

Query Parameters:

• client_id: - Account (public) API key associated with account.
• redirect_url: - where you would like the end user to be sent after auth
• response_type: - what you expect to receive back from the auth server. use 'code'
• scope: - what you are requesting access to. A space delimited permission list. "scope=basic email upload etc"

A request for permission to access a user's basic information and email address would look like the following:

https://api.dvidshub.net/auth/authorize?
client_id=[API_KEY_HERE]
&redirect_uri=[REDIRECT_URL_HERE]
&response_type=code
&scope=basic%20email

Upon landing, the user will be presented with a log-in form if they do not already have an active session. Once the user has logged in, he/she will be redirected to a page where they are presented with information about the permission request. The information page will display the requester domain/name, a list of requested permissions, along with a form giving the user the option to "authorize" access or "cancel" the request.

If accepted, the user will be redirected to the "redirect_url" provided with the request. The redirect request will also have a 'code' parameter that can then be used to request an access token.

If canceled, the user will be redirected to the "redirect_url" provided with the initial request sans the authorization code.

POST /auth/access_token

Requesting An Access Token

To obtain an access token, you will need to submit a backend (server) POST request to the /auth/access_token action. The following parameters are required:

• code: - The authorization code received on the previous request.
• client_id: - Account (public) API key associated with account.
• client_secret: - The secret key associated with the client_id in use.
• api_key: - The secret key associated with the client_id in use (must be passed with no referer present)
• grant_type: -'authorization_code'
• redirect_uri: - This must match the redirect_url for the original request.

A successful response will look like the following:

{
    "access_token":"92FIylE0b58AZGjsFCMv3OSNoejAYaRu73xIT43C",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"CezFzUBVr5k2GNJGEA1j0rm0PNDcvLe7PeibLFlc"
}

GET /auth/get-info

Requesting Token And Resource Information

Once you have obtained a valid access_token, you can use it to retrieve information about the user and other resources as they become available. To this this you will first need to call the /auth/get-info action to get the member ID number. The following parameters are required.

• api_key: - Public API key associated with account.
• access_token: - Can be sent as either a GET parameter or header "Authorization" parameter.

A request for information would look like the following:

https://api.dvidshub.net/auth/get-info?api_key=[API_KEY_HERE]

A successful response will look like the following:

{
  "owner_id": "[MEMBER_ID_HERE]",
  "owner_type": "member",
  "access_token": "zWIkr7Q7ZJf1ny31rZf38ueWMovdMjP3fgFP2veA",
  "client_id": "167",
  "scopes": {
    "basic": {
      "id": "basic",
      "description": "Basic details about your account"
    },
    "email": {
      "id": "email",
      "description": "Your email address"
    },
    "upload": {
      "id": "upload",
      "description": "Permission to upload assets on your behalf"
    }
  }
}

Example Work Flow

1. An anonymous user visits your site and clicks a registration link.
2. Your site initiates a request via GET for an authorization code to the DVIDS OAuth server.
3. The user is asked to login to the DVIDS OAuth Server and approve the permission request.
4. If approved the user is redirected with a response that contains an authorization code.
5. Your site then uses the authorization code to construct and submit a request for an access token.
6. If the request is successful, you will receive a JSON response containing an access token, a refresh token, and an expiration.
7. You can then use the access token to request additional resource information and interact with the DVIDS API on behalf of the user.

GET /members

Using Access Token

After fetching the member_id (owner_id) you can then use that value to fetch detailed member information. Member information request are handled by the RESTful /members controller. The following parameters are required:

• api_key: - Public API key associated with account.
• access_token: - Can be sent as either a GET parameter or header "Authorization" parameter.

A request for member information would look like the following:

https://api.dvidshub.net/members/[MEMBER_ID_HERE]?api_key=[API_KEY_HERE]