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.
- 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.
- 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.
- Your SBS app must be updated to have the client secrets as obtained from Google or Microsoft (this includes an application ID, a client ID, a client secret, and other configuration). You can perform this step either programmatically from the Account API or from the SBS Console, see Configure Google OAuth 2.0 Client Secrets and Configure Azure OAuth 2.0 Client Secrets.
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.
user
Returns a user by their ID.
Arguments
| Argument |
Type |
Description |
| id |
ID! |
Mandatory. The ID of the user to be retrieved. |
Result
See the User type.
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 |
| 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. If the provider is MICROSOFT, this value could be a string which is not necessarily a verified email. To set this value to a verified email, run the setVerifiedEmail mutation. |
| 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
generateEmailVerificationCode
Generates a numeric code that is valid for 5 minutes. The generated code must be supplied as input to the setVerifiedEmail mutation in order for it to succeed.
Arguments
| Attribute |
Type |
Description |
| userId |
ID! |
Mandatory. The ID of the user whose email is to be verified. |
| email |
EmailAddress! |
Mandatory. The email of the user whose email is to be verified. Note that the user’s email provider should be MICROSOFT. |
Result
The generated verification code, as a string.
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. |
setVerifiedEmail
When you sign in a user and the provider is MICROSOFT, the value returned in the User.email response field is not necessarily a verified email (for example, it may be a string such as a phone number of some user alias). If your app’s business requirements mandate that users have a verified email address, then you should implement an email validation outside of SBS, with the goal of obtaining the user’s verified email address. For example, your app may prompt the user to enter their email address and then send an email to their inbox. If the user confirms that they own the inbox (perhaps by clicking a verification link in the email message), then their email address is considered verified. Once you have the verified email address, run this mutation to set the email as verified in SBS as well.
Arguments
| Attribute |
Type |
Description |
| userId |
ID! |
Mandatory. The ID of the user whose email address is to be updated. |
| email |
EmailAddress! |
Mandatory. The verified email address. |
| verificationCode |
String! |
Mandatory. The verification code generated by the generateEmailVerificationCode mutation. |
Result
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.