Access info
|
|
Endpoint |
https://user-management-api.socrate.io/graphql |
Required access keys |
App-level service access key |
Pricing |
Please contact us for details at contact@bitsoftware.ro |
Notes |
To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to user-management-api:query:* user-management-api:mutation:* . |
Usage
The User Management Service provides calling apps the ability to authenticate users with existing Google or Microsoft accounts. Implementing this service means that users who already have a Google or Microsoft account will be able to sign into your app and use its resources. More specifically, the User Management Service provides the following features:
- Sign in users into your app with their Google or Microsoft account. This happens through OpenID Connect, without storing any credentials.
- Sign out users
- Exchange a refresh token for an access token, if the latter has expired
- Exchange an access token for a user ID.
Prerequisites
- Your app must be registered on the Google Cloud Platform or the Microsoft Azure platform, respectively. More specifically, your app must be configured to have a consent screen that will be displayed to the users when they grant permission to your app to access their Google or Microsoft profile. Also, your app must have a client ID and client secrets configured. Thirdly, your app’s scopes must include the
openid
grant. For details, see Configure an Azure App and Obtain OAuth 2.0 credentials from Google.
- Your app must be capable to issue an authorization request to Google or Microsoft and obtain a JSON Web Token (JWT) in the response (also known as “id token”). The JWT is required to sign the user into your app.
Queries
getUserId
Returns the ID of the user based on the access token provided as input.
Arguments
Argument |
Type |
Description |
access_token |
String! |
The access token obtained from the authorization server. |
Result
The SBS-generated ID of the user signed into your app.
users
Arguments
Argument |
Type |
Description |
filter |
UsersFilter |
Optional. Lets you specify user filtering options, as UsersFilter input. |
nextToken |
String |
Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the UsersResult type. |
All attributes of the UsersFilter
object are optional. If you specify multiple options, they will be connected by a logical AND.
Attribute |
Type |
Description |
ids |
ID |
Optional. A list of user IDs by which to filter. |
email |
EmailAddress |
Optional. Specifies the user’s email address as filtering option. |
provider |
Provider |
Optional. Specifies the OAuth 2.0 provider as filtering option. Valid values: GOOGLE, MICROSOFT. |
createdAt |
DateFilter |
Optional. Specifies a date range in which the user was created in SBS, as filtering option. |
Attribute |
Type |
Description |
from |
Date |
Optional. The start date of the date range. |
to |
Date |
Optional. The end date of the date range. |
Result
UsersResult
type
Attribute |
Type |
Description |
items |
User |
The list of users, where each user is an User type. |
nextToken |
String |
If null, then the query has reached the end of the list of invoices that match the query criteria. If not null, then use this value in the nextToken input argument to obtain the next page. |
User
type
Attribute |
Type |
Description |
id |
ID |
The SBS-generated identifier of the user. |
name |
String |
The user’s name obtained from the OpenID Provider. |
family_name |
String |
The user’s family name obtained from the OpenID Provider. |
given_name |
String |
The user’s given name obtained from the OpenID Provider. |
email |
EmailAddress |
The user’s email address obtained from the OpenID Provider. |
picture |
Uri |
The URI, obtained from the OpenID Provider, at which the user’s picture is available. |
provider |
Uri |
The OpenID Provider. This can be either GOOGLE or MICROSOFT. |
googleUserInfo |
GoogleUserInfo |
The user’s information retrieved from Google JWT token’s payload, as a GoogleUserInfo object. |
microsoftUserInfo |
MicrosoftUserInfo |
The user’s information retrieved from Microsoft JWT token’s payload, as a MicrosoftUserInfo object. |
createdAt |
DateTime |
The date and time when the user record was created in SBS. |
GoogleUserInfo
type
Attribute |
Type |
Description |
iss |
Uri |
The token’s issuer. |
sub |
String |
The token’s subject (that is, to whom this token refers). |
azp |
String |
The token’s authorized party (that is, the party to whom this token was issued). |
aud |
String |
The token’s audience. |
iat |
Float |
The timestamp when the token was issued. |
exp |
Float |
The timestamp when the token expires. |
email |
EmailAddress |
The email claim stored in the token. |
email_verified |
Boolean |
Specifies if the email is verified (true), false otherwise. |
name |
String |
The user’s name claim stored in the token. |
picture |
Uri |
The user’s picture URI claim stored in the token. |
given_name |
String |
The user’s given name claim stored in the token. |
family_name |
String |
The user’s family name claim stored in the token. |
locale |
String |
The user’s locale. |
MicrosoftUserInfo
type
Attribute |
Type |
Description |
sub |
String |
The token’s subject (that is, to whom this token refers). |
name |
String |
The user’s name claim stored in the token. |
email |
EmailAddress |
The email claim stored in the token. |
preferred_username |
String |
The user’s preferred username claim stored in the token. |
aud |
String |
The token’s audience. |
iat |
Float |
The timestamp when the token was issued. |
exp |
Float |
The timestamp when the token expires. |
version
Returns the API version.
Mutations
regenerateAccessToken
Obtains from the identity provider new tokens (including an access token), based on the refresh token supplied as input.
Arguments
Attribute |
Type |
Description |
refresh_token |
String! |
Mandatory. Supplies the refresh token to be used as input. |
Result
Token
type
Attribute |
Type |
Description |
access_token |
String |
The access token obtained from the OpenID provider. |
expires_in |
Float |
The access token’s expiry date. |
refresh_token |
String |
The refresh token obtained from the OpenID provider. |
user |
User |
See the User type. |
signIn
Authenticates an user based on the JSON Web Token (JWT) supplied as input.
Arguments
Attribute |
Type |
Description |
input |
SignInInput! |
Mandatory. The input to the sign in, as a SignInInput type. |
Attribute |
Type |
Description |
provider |
Provider! |
Mandatory. Specifies the identity provider. Valid values: GOOGLE, MICROSOFT. |
id_token |
String! |
Mandatory. The JSON Web Token (JWT) obtained from the identity provider. |
Result
See the Token
type.
signOut
Signs out an user based on the refresh token supplied as input.
Arguments
Attribute |
Type |
Description |
refresh_token |
String! |
Mandatory. The refresh token to be used as input. |
Result
See the User
type.