# Social Login API Reference

You can enable login via Social Login providers like Google/GitHub/LinkedIn etc. for your users by following [this guide](https://docs.propelauth.com/sso/social-login). The hosted pages will then include a button for your users to be able to login via these providers.

If you want to provide a link from your product directly, specify additional scopes, or if you want to receive the OAuth tokens returned by the provider, you can use the APIs below.

* * *

## [Login with OAuth Provider](https://docs.propelauth.com/reference/api/social-login#login-with-o-auth-provider)

This redirects the user to the OAuth provider's login page. This should be done in the browser.

You can optionally specify additional scopes, additional query parameters, and a redirect URL to send the user to after they have logged in.

### Provider Names

You must specify which OAuth provider you are logging in with, current options include:

- `google`
- `github`
- `gitlab`
- `linkedin`
- `microsoft`
- `slack`
- `salesforce`
- `xero`
- `quickbooks`
- `atlassian`
- `outreach`
- `salesloft`
- `apple`

### Query Parameters

- Name `scope`  Description

Additional scopes to request from the OAuth provider, separated by spaces. We automatically add any scopes needed for login (e.g. email openid profile).
  
  
  The Apple OAuth integration does not support additional scopes.

- Name `external_param_{name}`  Description

Additional query parameters to pass to the OAuth provider.

- Name `rt`  Description

The URL to redirect the user to after they have finished logging in. We handle the callback of the OAuth provider and redirect the user to this URL. The URL needs to be base64 encoded.

### URL

```text
{AUTH_URL}/{PROVIDER_NAME}/login
    ?external_param_login_hint=test@example.com
    &scope=repo+project
    &rt={base64("https://myapp.com")}
```

* * *

## [Link Social Account](https://docs.propelauth.com/reference/api/social-login#link-social-account)

This redirects the user to the OAuth provider's login page when using the [Social Account Linking](https://docs.propelauth.com/overview/authentication/login-methods#social-account-linking) feature. This should be done in the browser.

You can optionally specify additional scopes and query parameters.

### Provider Names

You must specify which OAuth provider you are logging in with, current options include:

- `google`
- `github`
- `gitlab`
- `linkedin`
- `microsoft`
- `slack`
- `salesforce`
- `xero`
- `quickbooks`
- `atlassian`
- `outreach`
- `salesloft`
- `apple`

### Query Parameters

- Name `scope`  Description

- Name `external_param_{name}`  Description

Additional query parameters to pass to the OAuth provider.

### URL

```text
{AUTH_URL}/api/fe/v3/{provider}/link
    ?external_param_login_hint=test@example.com
    &scope=repo+project
```

* * *

GET/api/backend/v1/user/<userId>/oauth_token

## [Fetch User OAuth Tokens](https://docs.propelauth.com/reference/api/social-login#fetch-user-o-auth-tokens)

Fetches a user's OAuth information if they logged in through a social OAuth provider. You can then use the included bearer token to make requests with the social provider. This should be done on your backend.

### Required Permissions

Read and Refresh Tokens from Social Providers

### Properties

- Name `userId` *Type string  Description The user's ID

### Request

Javascript Python Rust Go cURL

```
auth.fetchUserOAuthTokens("31c41c16-c281-44ae-9602-8a047e3bf33d")
```

### Successful Response

```
{
  google: {
      accessToken: "ya29.a0Ad52N3...",
      refreshToken: null,
      tokenProvider: "google",
      tokenExpiration: 1713366862,
      authorizedScopes: [
        "openid",
        "profile",
        "email"
      ]
  },
  github: {
      accessToken: "ghu_J...",
      refreshToken: "ghr_ldAnFa...",
      tokenProvider: "github",
      tokenExpiration: 1713499760,
      authorizedScopes: [
        "openid",
        "profile",
        "email"
      ]
  }
}
```

* * *

GET/api/backend/v1/user/<userId>/<provider>/fresh_token

## [Fetch Fresh Token From Provider](https://docs.propelauth.com/reference/api/social-login#fetch-fresh-token-from-provider)

Fetches a fresh token if the user logged in through a social OAuth provider. You can then use the included bearer token to make requests with the social provider. This should be done on your backend.

### Required Permissions

Read and Refresh Tokens from Social Providers

### Properties

- Name `userId` *Type string  Description The user's ID
- Name `provider` *Type string  Description The provider to fetch a token for. Must equal 'apple', 'google', 'github', 'microsoft', 'slack', 'salesforce', 'linkedin', outreach', 'quickbooks', 'xero', 'salesloft', 'atlassian', or 'gitlab'.

### Request

Javascript Python Rust Go cURL

```
auth.fetchFreshTokenFromProvider(
    "31c41c16-c281-44ae-9602-8a047e3bf33d",
    "google",
)
```

### Successful Response

```
{
    accessToken: "ya29.a0Ad52N3...",
    refreshToken: null,
    tokenProvider: "google",
    tokenExpiration: 1713366862,
    authorizedScopes: [
      "openid",
      "profile",
      "email"
    ]
}
```