Obtain Authorization Code

Obtain OAuth 2.0 Authorization Code:  GET /oauth2/authorize

Starts the OAuth 2.0 authorization flow.

Contents

Uses and Requirements

The OAuth 2.0 flow starts when a user is redirected to a web page that allows the user to log on to Verizon and authorize your application. After the user decides whether or not to authorize your app, they are redirected to the URI specified by the redirect_uri parameter.

  • If the user authorizes your app, a response containing an authorization code is sent to the HTTP callback address in the redirect_uri parameter. After retrieving the authorization code, the app should call POST /oauth2/token endpoint to exchange the authorization code for an access token.

  • If the user does not authorize your app, an error and the error description are added to the redirect_uri query string in the error field.

NOTE: The redirect_uri must match the Callback URL that you entered in Key Management when you registered the app, otherwise an error will be returned. Please, note that Callback URLs are case sensitive.

##Request Components

HTTP Request

GET https://api.cloudapi.verizon.com/cloud/1/oauth2/authorize

Header Parameters

None

Path Parameters

None

Query Parameters

Parameter Name Data Type Description
client_id
required
string OAuth 2 client identifier (key) obtained from the Key Management.
deviceid
optional
string An identifier of the device being authorized.

NOTES:
  • You must specify the deviceid during the authentication flow when your app uses the same client ID across multiple device types or platforms. Provide a unique ID for each device and use it consistently. For example, in most cases it is suffient to specify a string representing the platform used, such as Android or iOS.
  • If multiple developers are sharing the same ID during the development process, they must use their own device IDs.
redirect_uri
required
string Callback URI invoked after user authorization. If the authorization is successful, a code query string is included; otherwise, if the authorization is not successful an error query string is included.

NOTE: The value of the redirect_uri parameter must match the Callback URL you entered in the Key Management.
response_type
required
string OAuth 2 response type. Must be code.
state
optional
string This parameter is preserved in the authorization flow and returned to the client as a query string parameter in the call to redirect_uri. The client may validate this in order to protect against a Cross Site Request Forgery (XSRF) attempt.
The state parameter is optional. You can use it to store any alphanumeric string you chose.

Request Body

None

Success Responses

Status 302
Redirection to Verizon Cloud login page.

Failure Responses

  • Status 400
  • Status 401
  • Status 503

SEE ALSO:

{
	"swagger": "2.0",
	"info": {
		"title": "Personal Cloud Storage APIs",
		"version": "1"
	},
	"host": "api.cloudapi.verizon.com",
	"schemes": [
		"https"
	],
	"basePath": "/cloud/1/oauth2",
	"paths": {
		"/authorize": {
			"get": {
				"operationId": "get_authorize",
				"produces": [
					"*"
				],
				"summary": "Obtain an OAuth2 authorization code.",
				"description": "Redirects to a Verizon login page, where an end-user can sign in and grant a third-party application access to their cloud account. If access is granted, a response containing an authorization code is sent to the HTTP callback address 'redirect_uri'.  If not, redirect_uri will receive an HTTP request containing a query parameter 'error'. After successfully retrieving an authorization code, the client should call POST on the /token resource in order to exchange an authorization code for an access token.",
				"parameters": [
					{
						"$ref": "#/parameters/client_id_req"
					},
					{
						"$ref": "#/parameters/response_type"
					},
					{
						"$ref": "#/parameters/redirect_uri_req"
					},
					{
						"$ref": "#/parameters/state"
					},
					{
						"$ref": "#/parameters/deviceid"
					}
				],
				"responses": {
					"302": {
						"description": "Redirection to Verizon Cloud login page"
					},
					"400": {
						"description": "[Bad Request] client_id, response_type, or redirect_uri is missing, or response_type or redirect_uri is invalid.",
						"schema": {
							"$ref": "#/definitions/Error"
						}
					},
					"401": {
						"description": "[Unauthorized] client_id is not valid.",
						"schema": {
							"$ref": "#/definitions/Error"
						}
					},
					"503": {
						"description": "[Service Unavailable] See response body for more detail.",
						"schema": {
							"$ref": "#/definitions/Error"
						}
					}
				},
				"tags": [
					"Try it Out"
				],
				"x-auth-type": "None",
				"x-throttling-tier": "Unlimited"
			}
		}
	},
	"parameters": {
		"client_id_req": {
			"name": "client_id",
			"in": "query",
			"description": "OAuth 2 client identifier (key)",
			"required": true,
			"type": "string"
		},
		"response_type": {
			"name": "response_type",
			"in": "query",
			"description": "OAuth 2 response type.  Must be 'code'.",
			"required": true,
			"type": "string",
			"enum": [
				"code"
			]
		},
		"redirect_uri_req": {
			"name": "redirect_uri",
			"in": "query",
			"description": "Callback URI invoked after successful or unsuccessful user authorization. A 'code' query string is appended if successful and an 'error' query string if not.",
			"required": true,
			"type": "string"
		},
		"state": {
			"name": "state",
			"in": "query",
			"description": "This parameter is preserved in the authorization flow and returned to the client as a query string parameter in the 'redirect_uri'. The client may validate this in order to protect against a Cross Site Request Forgery (XSRF) attempt",
			"required": false,
			"type": "string"
		},
		"spc_token": {
			"name": "spc_token",
			"in": "query",
			"description": "SPC",
			"required": true,
			"type": "string"
		},
		"mdn": {
			"name": "mdn",
			"in": "query",
			"description": "MDN",
			"required": true,
			"type": "string"
		},
		"authorization": {
			"name": "Authorization",
			"in": "header",
			"description": "An HTTP Basic Access Authentication header, containing a value like: 'Basic TOKEN', where TOKEN is a base 64-encoded string of the pattern: 'client_id:client_secret'.  The values for client_id and client_secret are specific to a third-party application. An Authorization header is required, UNLESS client_id and client_secret are included in the request body.",
			"required": false,
			"type": "string"
		},
		"deviceid": {
			"name": "deviceid",
			"in": "query",
			"description": "An identifier for the device being authorized",
			"required": false,
			"type": "string"
		}
	},
	"definitions": {
		"token_response": {
			"properties": {
				"token_type": {
					"type": "string",
					"description": "OAuth 2 token type.  Should be 'Bearer'."
				},
				"expires_in": {
					"type": "integer",
					"description": "Time-to-live for the access token, in seconds."
				},
				"refresh_token": {
					"type": "string",
					"description": "OAuth 2 refresh token. Can be used in a subsequent call to /token (with grant_type=refresh_token), to obtain a fresh access token."
				},
				"access_token": {
					"type": "string",
					"description": "OAuth 2 access token."
				}
			}
		},
		"Error": {
			"properties": {
				"error": {
					"type": "string",
					"description": "An error"
				},
				"error_description": {
					"type": "string",
					"description": "Readable description of error"
				}
			}
		}
	}
}

Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.