Skip to content

Commit 18aafc6

Browse files
lbalmacedahzalaz
lbalmaceda
authored and
hzalaz
committed
add example snippets to the APIClient class
1 parent 2b99dc2 commit 18aafc6

1 file changed

Lines changed: 209 additions & 3 deletions

File tree

‎lib/src/main/java/com/auth0/authentication/AuthenticationAPIClient.java‎

Lines changed: 209 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -136,11 +136,23 @@ public void setDefaultDbConnection(String defaultDbConnection) {
136136
}
137137

138138
/**
139-
* Log in a user with email/username and password using a DB connection
139+
* Log in a user with email/username and password using a DB connection.
140+
* Example usage:
141+
* <pre><code>
142+
* client.login("username", "password")
143+
* .setConnection("second-database")
144+
* .start(new BaseCallback<Credentials>() {
145+
* {@literal@}Override
146+
* public void onSuccess(Credentials payload) { }
147+
* <p/>
148+
* {@literal@}Override
149+
* public void onFailure(Auth0Exception error) { }
150+
* });
151+
* </code></pre>
140152
*
141153
* @param usernameOrEmail of the user depending of the type of DB connection
142154
* @param password of the user
143-
* @return a request to configure and start that will yield {@link Credentials}
155+
* @return a request to configure and start that will yield{@link Credentials}
144156
*/
145157
public AuthenticationRequest login(String usernameOrEmail, String password) {
146158
Map<String, Object> requestParameters = ParameterBuilder.newAuthenticationBuilder()
@@ -153,6 +165,18 @@ public AuthenticationRequest login(String usernameOrEmail, String password) {
153165

154166
/**
155167
* Log in a user with a OAuth 'access_token' of a Identity Provider like Facebook or Twitter using <a href="https://auth0.com/docs/auth-api#!#post--oauth-access_token">'\oauth\access_token' endpoint</a>
168+
* Example usage:
169+
* <pre><code>
170+
* client.loginWithOAuthAccessToken("token", "my-connection")
171+
* .setConnection("second-database")
172+
* .start(new BaseCallback<Credentials>() {
173+
* {@literal@}Override
174+
* public void onSuccess(Credentials payload) { }
175+
* <p/>
176+
* {@literal@}Override
177+
* public void onFailure(Auth0Exception error) { }
178+
* });
179+
* </code></pre>
156180
*
157181
* @param token obtained from the IdP
158182
* @param connection that will be used to authenticate the user, e.g. 'facebook'
@@ -176,6 +200,17 @@ public AuthenticationRequest loginWithOAuthAccessToken(String token, String conn
176200

177201
/**
178202
* Log in a user using a phone number and a verification code received via SMS (Part of passwordless login flow)
203+
* Example usage:
204+
* <pre><code>
205+
* client.loginWithPhoneNumber("1234567890", "000000")
206+
* .start(new BaseCallback<Credentials>() {
207+
* {@literal@}Override
208+
* public void onSuccess(Credentials payload) { }
209+
* <p/>
210+
* {@literal@}@Override
211+
* public void onFailure(Auth0Exception error) { }
212+
* });
213+
* </code></pre>
179214
*
180215
* @param phoneNumber where the user received the verification code
181216
* @param verificationCode sent by Auth0 via SMS
@@ -194,6 +229,17 @@ public AuthenticationRequest loginWithPhoneNumber(String phoneNumber, String ver
194229

195230
/**
196231
* Log in a user using an email and a verification code received via Email (Part of passwordless login flow)
232+
* Example usage:
233+
* <pre><code>
234+
* client.loginWithEmail("email@example.com", "000000")
235+
* .start(new BaseCallback<Credentials>() {
236+
* {@literal@}Override
237+
* public void onSuccess(Credentials payload) { }
238+
* <p/>
239+
* {@literal@}@Override
240+
* public void onFailure(Auth0Exception error) { }
241+
* });
242+
* </code></pre>
197243
*
198244
* @param email where the user received the verification code
199245
* @param verificationCode sent by Auth0 via Email
@@ -212,6 +258,17 @@ public AuthenticationRequest loginWithEmail(String email, String verificationCod
212258

213259
/**
214260
* Fetch the token information from Auth0
261+
* Example usage:
262+
* <pre><code>
263+
* client.tokenInfo("idToken")
264+
* .start(new BaseCallback<UserProfile>() {
265+
* {@literal@}Override
266+
* public void onSuccess(UserProfile payload) { }
267+
* <p/>
268+
* {@literal@}@Override
269+
* public void onFailure(Auth0Exception error) { }
270+
* });
271+
* </code></pre>
215272
*
216273
* @param idToken used to fetch it's information
217274
* @return a request to start
@@ -223,6 +280,18 @@ public Request<UserProfile> tokenInfo(String idToken) {
223280

224281
/**
225282
* Creates a user in a DB connection using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-signup">'/dbconnections/signup' endpoint</a>
283+
* Example usage:
284+
* <pre><code>
285+
* client.createUser("email@example.com", "password", "username")
286+
* .setConnection("Username-Password-Authentication")
287+
* .start(new BaseCallback<DatabaseUser>() {
288+
* {@literal@}Override
289+
* public void onSuccess(DatabaseUser payload) { }
290+
* <p/>
291+
* {@literal@}@Override
292+
* public void onFailure(Auth0Exception error) { }
293+
* });
294+
* </code></pre>
226295
*
227296
* @param email of the user and must be non null
228297
* @param password of the user and must be non null
@@ -244,11 +313,23 @@ public DatabaseConnectionRequest<DatabaseUser> createUser(String email, String p
244313
.asDictionary();
245314
final ParameterizableRequest<DatabaseUser> request = factory.POST(url, client, mapper, DatabaseUser.class)
246315
.addParameters(parameters);
247-
return new DatabaseConnectionRequest(request);
316+
return new DatabaseConnectionRequest<>(request);
248317
}
249318

250319
/**
251320
* Creates a user in a DB connection using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-signup">'/dbconnections/signup' endpoint</a>
321+
* Example usage:
322+
* <pre><code>
323+
* client.createUser("email@example.com", "password")
324+
* .setConnection("Username-Password-Authentication")
325+
* .start(new BaseCallback<DatabaseUser>() {
326+
* {@literal@}Override
327+
* public void onSuccess(DatabaseUser payload) { }
328+
* <p/>
329+
* {@literal@}@Override
330+
* public void onFailure(Auth0Exception error) { }
331+
* });
332+
* </code></pre>
252333
*
253334
* @param email of the user and must be non null
254335
* @param password of the user and must be non null
@@ -261,6 +342,18 @@ public DatabaseConnectionRequest<DatabaseUser> createUser(String email, String p
261342
/**
262343
* Creates a user in a DB connection using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-signup">'/dbconnections/signup' endpoint</a>
263344
* and then logs in
345+
* Example usage:
346+
* <pre><code>
347+
* client.signUp("email@example.com", "password", "username")
348+
* .setConnection("Username-Password-Authentication")
349+
* .start(new BaseCallback<Credentials>() {
350+
* {@literal@}Override
351+
* public void onSuccess(Credentials payload) {}
352+
* <p/>
353+
* {@literal@}Override
354+
* public void onFailure(Auth0Exception error) {}
355+
* });
356+
* </code></pre>
264357
*
265358
* @param email of the user and must be non null
266359
* @param password of the user and must be non null
@@ -276,6 +369,18 @@ public SignUpRequest signUp(String email, String password, String username) {
276369
/**
277370
* Creates a user in a DB connection using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-signup">'/dbconnections/signup' endpoint</a>
278371
* and then logs in
372+
* Example usage:
373+
* <pre><code>
374+
* client.signUp("email@example.com", "password")
375+
* .setConnection("Username-Password-Authentication")
376+
* .start(new BaseCallback<Credentials>() {
377+
* {@literal@}Override
378+
* public void onSuccess(Credentials payload) {}
379+
* <p/>
380+
* {@literal@}Override
381+
* public void onFailure(Auth0Exception error) {}
382+
* });
383+
* </code></pre>
279384
*
280385
* @param email of the user and must be non null
281386
* @param password of the user and must be non null
@@ -289,6 +394,17 @@ public SignUpRequest signUp(String email, String password) {
289394

290395
/**
291396
* Request a change password using <a href="https://auth0.com/docs/auth-api#!#post--dbconnections-change_password">'/dbconnections/change_password'</a>
397+
* Example usage:
398+
* <pre><code>
399+
* client.requestChangePassword("email@example.com")
400+
* .start(new BaseCallback<Void>() {
401+
* {@literal@}Override
402+
* public void onSuccess(Void payload) {}
403+
* <p/>
404+
* {@literal@}Override
405+
* public void onFailure(Auth0Exception error) {}
406+
* });
407+
* </code></pre>
292408
*
293409
* @param email of the user that changes the password. It's also where the email will be sent with the link to perform the change password.
294410
* @return a request to configure and start
@@ -311,6 +427,17 @@ public DatabaseConnectionRequest<Void> requestChangePassword(String email) {
311427

312428
/**
313429
* Performs a <a href="https://auth0.com/docs/auth-api#!#post--delegation">delegation</a> request that will yield a new Auth0 'id_token'
430+
* Example usage:
431+
* <pre><code>
432+
* client.delegationWithIdToken("idToken")
433+
* .start(new BaseCallback<Delegation>() {
434+
* {@literal@}Override
435+
* public void onSuccess(Delegation payload) {}
436+
* <p/>
437+
* {@literal@}Override
438+
* public void onFailure(Auth0Exception error) {}
439+
* });
440+
* </code></pre>
314441
*
315442
* @param idToken issued by Auth0 for the user. The token must not be expired.
316443
* @return a request to configure and start
@@ -326,6 +453,17 @@ public DelegationRequest<Delegation> delegationWithIdToken(String idToken) {
326453
/**
327454
* Performs a <a href="https://auth0.com/docs/auth-api#!#post--delegation">delegation</a> request that will yield a new Auth0 'id_token'.
328455
* Check our <a href="https://auth0.com/docs/refresh-token">refresh token</a> docs for more information
456+
* Example usage:
457+
* <pre><code>
458+
* client.delegationWithRefreshToken("refreshToken")
459+
* .start(new BaseCallback<Delegation>() {
460+
* {@literal@}Override
461+
* public void onSuccess(Delegation payload) {}
462+
* <p/>
463+
* {@literal@}Override
464+
* public void onFailure(Auth0Exception error) {}
465+
* });
466+
* </code></pre>
329467
*
330468
* @param refreshToken issued by Auth0 for the user when using the 'offline_access' scope when logging in.
331469
* @return a request to configure and start
@@ -340,6 +478,17 @@ public DelegationRequest<Delegation> delegationWithRefreshToken(String refreshTo
340478

341479
/**
342480
* Performs a <a href="https://auth0.com/docs/auth-api#!#post--delegation">delegation</a> request that will yield a delegation token.
481+
* Example usage:
482+
* <pre><code>
483+
* client.delegationWithIdToken("idToken", "firebase")
484+
* .start(new BaseCallback<Map<String, Object>>() {
485+
* {@literal@}Override
486+
* public void onSuccess(Map<String, Object> payload) {}
487+
* <p/>
488+
* {@literal@}Override
489+
* public void onFailure(Auth0Exception error) {}
490+
* });
491+
* </code></pre>
343492
*
344493
* @param idToken issued by Auth0 for the user. The token must not be expired.
345494
* @param apiType the delegation 'api_type' parameter
@@ -356,6 +505,17 @@ public DelegationRequest<Map<String, Object>> delegationWithIdToken(String idTok
356505
/**
357506
* Performs a <a href="https://auth0.com/docs/auth-api#!#post--delegation">delegation</a> request that will yield a delegation token.
358507
* Check our <a href="https://auth0.com/docs/refresh-token">refresh token</a> docs for more information
508+
* Example usage:
509+
* <pre><code>
510+
* client.delegationWithRefreshToken("idToken", "firebase")
511+
* .start(new BaseCallback<Map<String, Object>>() {
512+
* {@literal@}Override
513+
* public void onSuccess(Map<String, Object> payload) {}
514+
* <p/>
515+
* {@literal@}Override
516+
* public void onFailure(Auth0Exception error) {}
517+
* });
518+
* </code></pre>
359519
*
360520
* @param refreshToken issued by Auth0 for the user when using the 'offline_access' scope when logging in.
361521
* @param apiType the delegation 'api_type' parameter
@@ -370,6 +530,17 @@ public DelegationRequest<Map<String, Object>> delegationWithRefreshToken(String
370530

371531
/**
372532
* Unlink a user identity calling <a href="https://auth0.com/docs/auth-api#!#post--unlink">'/unlink'</a> endpoint
533+
* Example usage:
534+
* <pre><code>
535+
* client.unlink("auth0|userId", "accessToken")
536+
* .start(new BaseCallback<Void>() {
537+
* {@literal@}Override
538+
* public void onSuccess(Void payload) {}
539+
* <p/>
540+
* {@literal@}Override
541+
* public void onFailure(Auth0Exception error) {}
542+
* });
543+
* </code></pre>
373544
*
374545
* @param userId of the identity to unlink
375546
* @param accessToken of the main identity obtained after login
@@ -392,6 +563,17 @@ public Request<Void> unlink(String userId, String accessToken) {
392563

393564
/**
394565
* Start a passwordless flow with <a href="https://auth0.com/docs/auth-api#!#post--with_email">Email</a>
566+
* Example usage:
567+
* <pre><code>
568+
* client.passwordlessWithEmail("email@example.com", PasswordlessType.CODE)
569+
* .start(new BaseCallback<Void>() {
570+
* {@literal@}Override
571+
* public void onSuccess(Void payload) {}
572+
* <p/>
573+
* {@literal@}Override
574+
* public void onFailure(Auth0Exception error) {}
575+
* });
576+
* </code></pre>
395577
*
396578
* @param email that will receive a verification code to use for login
397579
* @param passwordlessType indicate whether the email should contain a code, link or magic link (android & iOS)
@@ -410,6 +592,17 @@ public ParameterizableRequest<Void> passwordlessWithEmail(String email, Password
410592

411593
/**
412594
* Start a passwordless flow with <a href="https://auth0.com/docs/auth-api#!#post--with_sms">SMS</a>
595+
* Example usage:
596+
* <pre><code>
597+
* client.passwordlessWithSms("1234567890", PasswordlessType.CODE)
598+
* .start(new BaseCallback<Void>() {
599+
* {@literal@}Override
600+
* public void onSuccess(Void payload) {}
601+
* <p/>
602+
* {@literal@}Override
603+
* public void onFailure(Auth0Exception error) {}
604+
* });
605+
* </code></pre>
413606
*
414607
* @param phoneNumber where an SMS with a verification code will be sent
415608
* @param passwordlessType indicate whether the SMS should contain a code, link or magic link (android & iOS)
@@ -428,6 +621,18 @@ public ParameterizableRequest<Void> passwordlessWithSMS(String phoneNumber, Pass
428621
/**
429622
* Performs a custom <a href="https://auth0.com/docs/auth-api#!#post--delegation">delegation</a> request that will
430623
* yield a delegation token.
624+
* Example usage:
625+
* <pre><code>
626+
* client.delegation()
627+
* .addParameter("api_type", "firebase")
628+
* .start(new BaseCallback<Map<String, Object>>() {
629+
* {@literal@}Override
630+
* public void onSuccess(Map<String, Object> payload) {}
631+
* <p/>
632+
* {@literal@}Override
633+
* public void onFailure(Auth0Exception error) {}
634+
* });
635+
* </code></pre>
431636
*
432637
* @return a request to configure and start
433638
*/
@@ -479,6 +684,7 @@ public ParameterizableRequest<Void> passwordless() {
479684
/**
480685
* Fetch the user's profile after it's authenticated by a login request.
481686
* If the login request fails, the returned request will fail
687+
*
482688
* @param authenticationRequest that will authenticate a user with Auth0 and return a {@see Credentials}
483689
* @return a {@see ProfileRequest} that first logins and the fetches the profile
484690
*/

0 commit comments

Comments
 (0)