These docs are for AuthRocket 1. Looking for AuthRocket 2 docs?

Social Login via Auth Providers

The Auth Providers resource is split into two parts:

Logins/authentication (part of the Core API)
Configuration (part of the Extended API)

This document covers the Core API functionality: authentication via external auth providers, such as social login. For the Extended API, see Auth Providers. For authentication via password, see Users.

Fields

Field	Value	Req/Default	Notes
`id`	id	Auto-generated	Provider’s ID. Always starts with “ap_”. Example: `ap_USkZSudITtpKPqQcyxU84`
`provider_type`	string
`realm_id`	realm_id		ID of Realm this Provider belongs to.
`request`	hash		Hash of request attributes to add to Event. See notes.

Permissions

Method	Permissions
List URLs, Get URL	read
Authenticate, Authenticate Token	write

List authorization URLs

List authorization URLs for all active social and third-party auth providers in the current realm.

Use the returned URLs to build links or buttons when building your own login page. Returned URLs are valid for 30 minutes.

Not needed when using hosted logins.

Parameters

Param	Value	Default
`redirect_uri`	url		URL in your app that will receive the incoming OAuth token (and send it back to AuthRocket).
`nonce`	string		Optional, but encouraged. A random string stored in the user's session in your app. Basically a CRSF check.

Request

Example

GET /v1/auth_providers/authorize?redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth

$res = $client->authProviders()->authorizeUrls([
  "redirect_uri" => "https://myapp.com/oauth"
]);

AuthRocket::AuthProvider.authorize_urls(redirect_uri: 'https://myapp.com/oauth',
  realm_id: 'rl_0v76O8itSEiwfhA64ZFvKj')

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "ap_0v9XwmNDu1eHFAnDgYxHgb",
      "provider_type" : "facebook",
      "url" : "https://www.facebook.com/v...clFSZz09"
    }
  ]
}

var_dump($res->results);
  array(1) {
    [0]=>
    array(3) {
      ["id"]=> string(25) "ap_0v9XwmNDu1eHFAnDgYxHgb"
      ["provider_type"]=> string(8) "facebook"
      ["url"]=> string(391) "https://www.facebook.com/v...clFSZz09"
    }
  }

[#<AuthRocket::GenericObject:0x3fc21aab662c>
  id: "ap_0v9XwmNDu1eHFAnDgYxHgb",
  attribs: {
    "provider_type"=>"facebook",
    "url"=>"https://www.facebook.com/v...clFSZz09"
  },
  metadata: {
    "more_results"=>false
  }
]

Get a provider's authorization URL

Retrieve the authorization URL for one active social or third-party auth provider in the current realm.

Use the returned URL to build a link or button when building your own login page. Returned URL is valid for 30 minutes.

Not needed when using hosted logins.

Parameters

Param	Value	Default
`redirect_uri`	url		URL in your app that will receive the incoming OAuth token (and send it back to AuthRocket).
`nonce`	string		Optional, but encouraged. A random string stored in the user's session in your app. Basically a CRSF check.

Request

Example

GET /v1/auth_providers/:provider_id/authorize?redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth
GET /v1/auth_providers/:provider_type/authorize?redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth

$res = $client->authProviders()->authorizeUrl('ap_0v9XwmNDu1eHFAnDgYxHgb', [
  "redirect_uri" => "https://myapp.com/oauth"
]);
$res = $client->authProviders()->authorizeUrl('facebook', [
  "redirect_uri" => "https://myapp.com/oauth"
]);

AuthRocket::AuthProvider.authorize_url('ap_0v9XwmNDu1eHFAnDgYxHgb',
  redirect_uri: 'https://myapp.com/oauth')
AuthRocket::AuthProvider.authorize_url('facebook', redirect_uri: 'https://myapp.com/oauth',
  realm_id: 'rl_0v76O8itSEiwfhA64ZFvKj')

ap=AuthRocket::AuthProvider.find 'ap_0v9XwmNDu1eHFAnDgYxHgb'
ap.authorize_url redirect_uri: 'https://myapp.com/oauth'

Response

Example

Status: 200

{ "id" : "ap_0v9XwmNDu1eHFAnDgYxHgb",
  "provider_type" : "facebook",
  "url" : "https://www.facebook.com/v...clFSZz09"
}

var_dump($res->fields);
  array(3) {
    ["id"]=> string(25) "ap_0v9XwmNDu1eHFAnDgYxHgb"
    ["provider_type"]=> string(8) "facebook"
    ["url"]=> string(391) "https://www.facebook.com/v...clFSZz09"
  }

"https://www.facebook.com/v...clFSZz09"

Authenticate using a provider's token

Accepts a provider’s token (authorization code), verifies it, and completes a login for the user.

Does for social and third-party authentication what Authenticate a User does for password logins, including creating login events and sessions.

Will auto-associate a social or third-party profile with an existing user, based on email address. If one is not found, will auto-create a new User. Auto-creating users happens regardless of values for signup and signup_mode on the LoginRocket Auth Provider.

Existing users must be humans and active.

If you are starting with an access token (instead of an authorization code), most likely from an iOS or Android SDK, use Authenticate using an access token instead.

Parameters

Param	Value
`code`	string	`code` parameter sent to your app (at your `redirect_uri`) by the external provider. Required (unless `error` is provided).
`error`	string	If the external provider sends you `error` instead of `code`, you may handle that or pass it on to us, where we’ll turn it into our standard error format.
`nonce`	string	If provided to /authorize above, must send the same value here. You do not need to verify them; we will do it.
`state`	string	`state` parameter sent to your app by the external provider. Required.

Request

Example

POST /v1/auth_providers/authorize

{ "code" : "ACQ51...KnJAS",
  "state" : "ZWhCF...J3dmc",
  "request" : {
    "ip" : "127.0.0.1",
    "client" : "user's User-Agent header"
  }
}

$res = $client->authProviders()->authorize([
  "code" => "ACQ51...KnJAS",
  "state" => "ZWhCF...J3dmc"
]);

user=AuthRocket::AuthProvider.authorize(code: params['code'],
  error: params['error'], state: params['state'])

Response

Example

Status: 200 with same body as Authenticate a User.

Status: 422 if there was an error. When possible, includes a retry URL with the error:

{ ... ,
  "retry_url" : "4JagCZeSCVH...ae2kd9ZOaWo"
}

The retry URL is the same as from Get an Authorization URL above, with the addition of anything required by the provider to indicate this is a retry.

On success, returns a user object with token, same as Authenticate a User.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(16) "State is invalid"
  }

Will also add a retry URL, which is the same as from Get an Authorization URL above, with the addition of anything required by the provider to indicate this is a retry.

$res->metadata["retry_url"];
// => "https://www.facebook.com/v...clFSZz09"

On success, returns a user object with token, same as Authenticate a User.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::User:0x3fde5fa18df8> id: nil, ...
user.errors?
# => true
user.valid?
# => false
user.errors
# => ["State is invalid"]

Will also add a retry URL, which is the same as from Get an Authorization URL above, with the addition of anything required by the provider to indicate this is a retry.

user.metadata[:retry_url]
# => "https://www.facebook.com/v...clFSZz09"

Events

On success, triggers a user.login.succeeded event.

If a new Credential was added to an existing user (it was their first login with this provider), triggers a user.updated event.

If a new user was created, triggers a user.created event.

Authenticate using an access token

Accepts a provider’s access token (already converted from an auth code) and completes a login for the user.

This is used when implementing authorization in native apps (typically iOS or Android), with a social vendor’s SDK that automatically converts authorization codes into access tokens for you. If you are starting with an authorization code, use Authenticate using a provider’s token instead.

Performs authentications, auto-association with users, and creates events like Authenticate using a provider’s token above.

If the token is expired or otherwise unusable, does not return a retry_url (in contrast to Authenticate using a provider’s token).

Parameters

Param	Value	Default
`access_token`	string		Valid access_token for the external provider. Required.

Request

Example

POST /v1/auth_providers/:id/authorize

{ "access_token" : "JD7fD...jd8Nb2",
  "request" : {
    "ip" : "127.0.0.1",
    "client" : "user's User-Agent header"
  }
}

$res = $client->authProviders()->authorizeToken('ap_0v9XwmNDu1eHFAnDgYxHgb', [
  "access_token" => "JD7fD...jd8Nb2"
]);

provider=AuthRocket::AuthProvider.find 'ap_0v9XwmNDu1eHFAnDgYxHgb'
user=provider.authorize_token(access_token: params['access_token'])

Response

Example

Status: 200 with same body as Authenticate a User.

Status: 422 if there was an error.

On success, returns a user object with token, same as Authenticate a User.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(23) "Access token is invalid"
  }

On success, returns a user object with token, same as Authenticate a User.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::User:0x3fde5fa18df8> id: nil, ...
user.errors?
# => true
user.valid?
# => false
user.errors
# => ["Access token is invalid"]

Events

On success, triggers a user.login.succeeded event.

If a new Credential was added to an existing user (it was their first login with this provider), triggers a user.updated event.

If a new user was created, triggers a user.created event.

Questions? Find a Typo? Get in touch.

Back to All Docs

Documentation

Knowledgebase

Social Login via Auth Providers

Fields

Permissions

List authorization URLs

Parameters

Request

Example

Response

Example

Get a provider's authorization URL

Parameters

Request

Example

Response

Example

Authenticate using a provider's token

Parameters

Request

Example

Response

Example

Events

Authenticate using an access token

Parameters

Request

Example

Response

Example

Events