REST API

This is a reference for JustAuthenticateMe's simple public REST API. If you aren't using the Node SDK, you'll need this.

All paths assume a base URL of https://api.justauthenticate.me

Initiate Authenticating a User Email

Method: POST

Path: /:appId/authenticate

Path Parameters:

  • appId: Your app ID as found in the JustAuthenticateMe console.

JSON Body Parameters:

  • email: The email address of the user you'd like to authenticate.

Body Example:

{
  "email": "someone@example.com"
}

Responses:

  • 200: Indicates that a magic link email was succesfully sent to the email address specified.
  • 400: Indicates that the request was incorrectly formatted in some way.
    • Example:
      {
        "message": "email required"
      }
  • 404: Indicates that the app corresponding to the appId was not found.
    • Example:
      {
        "message": "app not found"
      }

Fetch App Public Key JWKS

Method: GET

Path: /:appId/.well-known/jwks.json

Path Parameters:

  • appId: Your app ID as found in the JustAuthenticateMe console.

Responses:

  • 200: Contains the public key in JWKS format
    • Example:
      {
        "keys": [
          {
            "kty": "EC",
            "crv": "P-521",
            "x": "AAxITIcrVaa7EekcwGUAK5bBkbZyCoqm_IcT--XoU4ZgDVcs4z52AZJEuoNSHm36ctarc9AASTN1nnnQQNkdKqWu",
            "y": "Adbm2Ua6bKpQr30Ytwa9amKachE6ZGLOOrxzYUuEZHCVp_nQi9ZKgwjAYSDbrIdGoe-TGFaPe3XVQK-6FpJndebs",
            "kid": "2eb40104-dc45-4f37-b69c-937b6386b9f6"
          }
        ]
      }
  • 404: Indicates that the app corresponding to the appId was not found.
    • Example:
      {
        "message": "app not found"
      }

Use Refresh Token to get new ID Token

Method: POST

Path: /:appId/refresh

Path Parameters:

  • appId: Your app ID as found in the JustAuthenticateMe console.

JSON Body Parameters:

  • refreshToken: The valid refresh token of the user who needs a new ID token.

Body Example:

{
  "refreshToken": "c3VwcG9ydEBqdXN0YXV0aGVudGljYXRlLm1l.1bcW+CuiSmeagaolgqfiH5zrRa3s3ViX3g5CFBVt6RuP6kc742QV0GDI6El0mfVbJVMiYvqQjUgGldPMe6hiYtfNpO8nWjOetlaYYDcB7uY2c/P7j7GMJOI1P2mfHCVQNLukvb1OXQ569k3rCBYlGrDAiVZStnJ2MOtM4d/83Y8="
}

Responses:

  • 200: Indicates that the refresh token is valid and an ID token was successfully generated. Contains the new ID token.
    • Example:
      {
        "idToken": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IjJlYjQwMTA0LWRjNDUtNGYzNy1iNjljLTkzN2I2Mzg2YjlmNiJ9.eyJlbWFpbCI6InN1cHBvcnRAanVzdGF1dGhlbnRpY2F0ZS5tZSIsInN1YiI6InN1cHBvcnRAanVzdGF1dGhlbnRpY2F0ZS5tZSIsImF1ZCI6ImIxOWEyMWI0LWFkOWQtNGZkNy04OGMxLTFiNjhiODI1YzY3MSIsImlzcyI6Imh0dHBzOi8vZGV2LWFwaS5qdXN0YXV0aGVudGljYXRlLm1lL2IxOWEyMWI0LWFkOWQtNGZkNy04OGMxLTFiNjhiODI1YzY3MSIsImp0aSI6IjZhMjJjOTEyLWYwMzYtNGU0Mi1iZjM5LTQ3N2ZhM2ExOGY2ZCIsInRva2VuX3VzZSI6ImlkIiwiaWF0IjoxNTgzNjk1NDM5LCJuYmYiOjE1ODM2OTU0MzksImV4cCI6MTU4MzY5NzIzOX0.AZqvVWSXn4zwP4WhYOL-nQEDDEMa4Cmpyx8HGJ-6uc3wLeZVfvil6RyAlUExnd6JpteaAImOrKo5fnv93SSGkP-eAN9igGRg0GmXpIeGno_sY_4rMLXDa6RtABL1lz5LCYMxD79oIYIflWJ-LVqmCF90msq-PysFZcgKVLa8oki8ZlKI"
      }
  • 400: Indicates that the app doesn't allow refresh, or that the request was incorrectly formatted in some way.
    • Example:
      {
        "message": "app doesn't allow refresh"
      }
  • 401: Indicates that the refreshToken was invalid or expired.
  • 404: Indicates that the app corresponding to the appId or the refreshToken itself was not found.
    • Example:
      {
        "message": "refresh token not found"
      }

Delete Refresh Token

Method: DELETE

Path: /:appId/user/refresh/:refreshToken

Expected Headers:

  • Authorization: Expected to be Bearer ${idToken}, where ${idToken} is replaced with the user's valid ID token.

Path Parameters:

  • appId: Your app ID as found in the JustAuthenticateMe console.
  • refreshToken: The user's refresh token to delete.

Responses:

  • 204: Indicates that the refresh token was successfully deleted and will no longer be accepted by JustAuthenticateMe.
  • 401: Indicates that the ID token in the Authorization header is invalid.
  • 404: Indicates that the refreshToken to delete or the app corresponding to the appId was not found.
    • Example:
      {
        "message": "refresh token not found"
      }

Delete All User's Refresh Tokens (Sign Out Everywhere)

Method: DELETE

Path: /:appId/user/refresh

Expected Headers:

  • Authorization: Expected to be Bearer ${idToken}, where ${idToken} is replaced with the user's valid ID token.

Path Parameters:

  • appId: Your app ID as found in the JustAuthenticateMe console.

Responses:

  • 204: Indicates that all refresh tokens for this user were successfully deleted and will no longer be accepted by JustAuthenticateMe.
  • 401: Indicates that the ID token in the Authorization header is invalid.

Verify ID Token

Method: POST

Path: /:appId/verify

Path Parameters:

  • appId: Your app ID as found in the JustAuthenticateMe console.

JSON Body Parameters:

  • idToken: The ID token that you'd like to verify.

Body Example:

{
  "idToken": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IjJlYjQwMTA0LWRjNDUtNGYzNy1iNjljLTkzN2I2Mzg2YjlmNiJ9.eyJlbWFpbCI6InN1cHBvcnRAanVzdGF1dGhlbnRpY2F0ZS5tZSIsInN1YiI6InN1cHBvcnRAanVzdGF1dGhlbnRpY2F0ZS5tZSIsImF1ZCI6ImIxOWEyMWI0LWFkOWQtNGZkNy04OGMxLTFiNjhiODI1YzY3MSIsImlzcyI6Imh0dHBzOi8vZGV2LWFwaS5qdXN0YXV0aGVudGljYXRlLm1lL2IxOWEyMWI0LWFkOWQtNGZkNy04OGMxLTFiNjhiODI1YzY3MSIsImp0aSI6IjZhMjJjOTEyLWYwMzYtNGU0Mi1iZjM5LTQ3N2ZhM2ExOGY2ZCIsInRva2VuX3VzZSI6ImlkIiwiaWF0IjoxNTgzNjk1NDM5LCJuYmYiOjE1ODM2OTU0MzksImV4cCI6MTU4MzY5NzIzOX0.AZqvVWSXn4zwP4WhYOL-nQEDDEMa4Cmpyx8HGJ-6uc3wLeZVfvil6RyAlUExnd6JpteaAImOrKo5fnv93SSGkP-eAN9igGRg0GmXpIeGno_sY_4rMLXDa6RtABL1lz5LCYMxD79oIYIflWJ-LVqmCF90msq-PysFZcgKVLa8oki8ZlKI"
}

Responses:

  • 200: Indicates that the ID token signature passed verification.
  • 400: Indicates that the request was incorrectly formatted in some way.
    • Example:
      {
        "message": "idToken required"
      }
  • 401: Indicates that the ID token signature failed verification.
  • 404: Indicates that the app corresponding to the appId was not found.
    • Example:
      {
        "message": "app not found"
      }