supabase/web/spec/gotrue.yml

openref: 0.1

info:
  id: reference/gotrue-js
  title: GoTrue Client
  description: |
    GoTrue is an authentication server.

    Supabase provides client libraries to interact with the server

  definition: spec/gotrue.json
  libraries:
    - name: 'JavaScript'
      id: 'js'
      version: '0.0.1'
    - name: 'Python'
      id: 'py'
      version: '0.0.1'
  docs:
    path: gotrue/client/
    sidebar:
      - name: 'About'
        items:
          - index
          - Installing
          - Initializing
      - name: 'Client functions'
        items:
          - signUp
          - signIn
          - signOut
          - user
          - session
          - update
          - onAuthStateChange
      - name: 'General functions'
        items:
          - api.signUpWithEmail
          - api.signInWithEmail
          - api.sendMagicLinkEmail
          - api.inviteUserByEmail
          - api.resetPasswordForEmail
          - api.signOut
          - api.getUser
          - api.updateUser
          - api.refreshAccessToken

pages:
  Installing:
    description: |
      All JavaScript libraries are built directly by the Supabase team. 

      Other languages are built by the community and supported by Supabase.

      ## JavaScript

      ```bash
      npm install @supabase/gotrue-js
      ```

      ## Python

      ```bash
      # Not yet implemented
      ```

  Initializing:
    $ref: '"GoTrueClient".GoTrueClient.constructor'
    examples:
      - name: Initialize a GoTrue client
        isSpotlight: true
        js: |
          ```js
          import { GoTrueClient } from '@supabase/gotrue-js'

          const auth = new GoTrueClient({
            url: "https://your-gotrue-url.com",
            headers: {
              apikey:
                "<SOME-API-KEY>",
              Authorization:
                "Bearer <SOME-JWT>",
            },
          })
          ```
        py: |
          ```py
          # Not yet implemented
          ```

  signUp:
    $ref: '"GoTrueClient".GoTrueClient.signUp'
    notes: |
      - A user can sign up either via email or OAuth.
      - If you provide `email`, `password` is also required
      - If you provide `access_token`, `password` is also required
    examples:
      - name: Sign up
        js: |
          ```js
          const { user, session, error } = await auth.signUp({
            email: 'example@email.com',
            password: 'example-password',
          })
          ```
        py: |
          ```py
          # Not yet implemented
          ```

  signIn:
    $ref: '"GoTrueClient".GoTrueClient.signIn'
    examples:
      - name: Sign in
        isSpotlight: true
        js: |
          ```js
          // with email and password
          const { user, error } = await auth.signIn({
            email: 'example@email.com',
            password: 'example-password',
          })

          // send magic link (passwordless link)
          const { user, session, error } = await auth.signIn({
            email: 'example@email.com',
          })
          ```
        py: |
          ```py
          # Not yet implemented
          ```

  signOut:
    $ref: '"GoTrueClient".GoTrueClient.signOut'
    examples:
      - name: Sign out
        js: |
          ```js
          const { error } = await auth.signOut()
          ```

  user:
    $ref: '"GoTrueClient".GoTrueClient.user'
    examples:
      - name: Get user
        js: |
          ```js
          const user = await auth.user()
          ```

  session:
    $ref: '"GoTrueClient".GoTrueClient.session'
    examples:
      - name: Get user
        js: |
          ```js
          const session = auth.session()
          ```

  update:
    $ref: '"GoTrueClient".GoTrueClient.update'
    examples:
      - name: Update a user's metadata.
        isSpotlight: true
        js: |
          ```js
          const { user, error } = await auth.update({ 
            data: { hello: 'world' } 
          })
          ```
        py: |
          ```py
          # Not yet implemented
          ```
      - name: Update a user's email address.
        isSpotlight: true
        js: |
          ```js
          const { user, error } = await auth.update({
            email: 'new-email@example.com'
          }) // Sends a "Confirm Email Change" email to the new email address
          ```
        py: |
          ```py
          # Not yet implemented
          ```

  onAuthStateChange:
    $ref: '"GoTrueClient".GoTrueClient.onAuthStateChange'
    examples:
      - name: Listen to auth changes
        isSpotlight: true
        js: |
          ```js
          supabase.auth.onAuthStateChange((event, session) => {
            console.log(event, session)
          })
          ```
        py: |
          ```py
          # Not yet implemented
          ```

  api.signUpWithEmail:
    $ref: '"GoTrueApi".GoTrueApi.signUpWithEmail'
    examples:
      - name: Sign up a new user with email
        js: |
          ```js
          const { error, data } = await auth.api
            .signUpWithEmail('example@email.com', 'example-password')
          ```

  api.signInWithEmail:
    $ref: '"GoTrueApi".GoTrueApi.signInWithEmail'
    examples:
      - name: Sign in a user with email
        js: |
          ```js
          const { error, data } = await auth.api
            .signInWithEmail('example@email.com', 'example-password')
            ```

  api.sendMagicLinkEmail:
    $ref: '"GoTrueApi".GoTrueApi.sendMagicLinkEmail'
    notes: |
      - An account is created when a non-existing user email is passed.
    examples:
      - name: Send user a passwordless login link via email
        js: |
          ```js
          const { error, data } = await auth.api
            .sendMagicLinkEmail('example@email.com')
            ```

  api.inviteUserByEmail:
    $ref: '"GoTrueApi".GoTrueApi.inviteUserByEmail'
    examples:
      - name: Send a user an invite link to sign up via email
        js: |
          ```js
          const { error, data } = await auth.api
            .inviteUserByEmail('example@email.com')
            ```

  api.resetPasswordForEmail:
    $ref: '"GoTrueApi".GoTrueApi.resetPasswordForEmail'
    notes: |
      Sends a reset request to an email address.

      When the user clicks the reset link in the email they will be forwarded to:
      
      `<SITE_URL>#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=recovery`

      Your app must detect `type=recovery` in the fragment and display a password reset form to the user.

      You should then use the access_token in the url and new password to update the user as follows:

      ```js
      const { error, data } = await auth.api
            .updateUser(access_token, { password : new_password })
      ```
    examples:
      - name: Send a user a password reset email
        js: |
          ```js
          const { error, data } = await auth.api
            .resetPasswordForEmail('example@email.com')
            ```

  api.signOut:
    $ref: '"GoTrueApi".GoTrueApi.signOut'
    examples:
      - name: Sign a user out
        js: |
          ```js
          const { error, data } = await auth.api
            .signOut(access_token)
            ```

  api.getUser:
    $ref: '"GoTrueApi".GoTrueApi.getUser'
    examples:
      - name: Get the user details for a given user
        js: |
          ```js
          const { error, data } = await auth.api
            .getUser(access_token)
            ```

  api.updateUser:
    $ref: '"GoTrueApi".GoTrueApi.updateUser'
    notes: |
      Updating the `email` field will cause a "Confirm Email Change" email to be sent to the new address.

      When the user clicks the Confirm link in the Confirm Change email they will be forwarded to:

      `<SITE_URL>?email_change_token=x&type=email_change&redirect_to=y`

      Your app must detect the `email_change_token` in the search params.

      You should then use the `email_change_token` in the url to update the user's email as follows:

      ```js
      const { error, data } = await supabase.auth.update({
        email_change_token: emailChangeToken,
      });
      ```
    examples:
      - name: Update user info that Gotrue holds (also used for setting new passwords)
        js: |
          ```js
          const { error, data } = await auth.api
            .updateUser(access_token, { password : 'Why Shinji?' })
            ```

  api.refreshAccessToken:
    $ref: '"GoTrueApi".GoTrueApi.refreshAccessToken'
    examples:
      - name: Get a new access and refresh token using a valid refresh_token
        js: |
          ```js
          const { error, data } = await auth.api
            .refreshAccessToken(refresh_token)
            ```