Skip to content

Get Authorization URL

Description

This API is used to obtain a URL for the login providers authorization (login) form. The API is used in the OAuth login approach without using login provider's SDK (see Step 1 in Login Without Provider's SDK).

Method

POST

Endpoint URL

Important

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/users/oauth/<providerCode>/request_url

where:

Argument                Description
<providerCode> value from Backendless Console on the Users > Login Providers screen.

Request Headers

Content-Type:application/json

where

Argument                Description
Content-Type must be set to application/json. This header is mandatory.

Request Body

{  
  "fieldsMapping": <String>,  
  "permissions": <String>,  
  "redirect": <boolean>,  
  "contentType": <String>,  
  "callbackUrlDomain": <String>  
}

where:

Argument                Description
fieldsMappings Optional property. A mapping of user properties between OAuth provider and Backendless. If the map object is not null, it should contain a mapping between the provider specific property names and the column names in the Users table. Consider the following mappings:
"my_email" >> "email"
"my_name" >> "name"
The key identifies the provider's property name and the value is the name of the mapped property (column name) in Backendless. In the example above, "my_email" and "my_name" are the properties returned by the OAuth2 provider and the corresponding values will be respectively stored in the "email" and "name" columns in Backendless.
permissions Optional property. Applies only to the OAuth2 providers. Contains provider scopes for data access. If omitted, default provider scopes will be used.
redirect Indicates if the server should return authorization URL or redirect to it. If the field is omitted, the server performs an HTTP redirect.
contentType Optional property. Is used to specify the format of the response. Can have one of the following values: "text/plain" - in this case, the API response is the authorization URL in the plain text format. This is the same behavior when the "contentType" property is not set."application/json" - in this case, the API response is a JSON document with the structure shown in the Response Body section below. In order for this property to work, the redirect property must be set to false.
callbackUrlDomain Allows customizing the callback URL which is used during the authorization process. By default, if the value for this parameter is not provided or set to null, the server will return the provider's authorization URL. However, when you provide a valid value for this parameter, the server will generate the URL with a callback that utilizes the specified domain. This feature allows you to tailor the callback URL according to your specific needs and enhance the authorization process for your application.

Response Body

The method returns an authorization URL. It should be used to open up the provider's login form.

  • If the redirect parameter is set to true, then the server will respond with an HTTP redirect to the authorization URL.
  • If the redirect parameter is set to false and the contentType parameter in the request body is not specified, the server returns authorization URL as plain text.
  • If the redirect parameter is set to false and the contentType parameter in the request body is set to "application/json".

The object in the response has the following structure:

{          
  "url": "authorization URL"  
}

Example

The example below retrieves the authorization URL for facebook.

curl --location --request POST 'https://xxxx.backendless.app/api/users/oauth/facebook/request_url