API Keys, Access Tokens, and User Creation/Login with the Propeller GraphQL API

This tutorial provides an overview of how to use API keys, create customers, companies and contacts, authenticate sessions, and implement security practices using Propeller Commerce’s GraphQL API. These steps are essential for accessing Propeller’s eCommerce functionalities.

Why It's Important

Propeller Commerce allows businesses to create accounts, generate API tokens, and access its platform using secure authentication mechanisms. Proper authentication is crucial to protect sensitive data and ensure that only authorized users can interact with the system. By following this guide, you will be able to integrate secure API-based interactions into your ordering portal.

Key Topics Covered

1. API Keys for GraphQL Queries
2. User Registration and Account Creation
3. Access and Refresh tokens

1. API Keys for GraphQL Queries

Propeller Commerce provides two types of API keys for GraphQL queries:

1. System API Key: This key has access to all data and should be treated with the highest level of security. It must never be exposed in front-end or client applications to prevent unauthorized access to sensitive data. This key is intended for server-side use only.

2. Limited API Key: This key provides anonymous access and is designed for use in front-end or client applications. It allows the creation of e.g. customers, companies, contacts, addresses, and carts, as well as browsing products, without exposing sensitive data. This key ensures that only limited operations can be performed, supporting eCommerce functionality for users who are not logged in, and maintaining a secure interaction with the Propeller API. This is the key to use in front-end or client code.

2. User Registration and Account Creation

In Propeller, user registration involves creating either a customer or a contact. A customer is typically a B2C user, while a contact is a B2B user and is stored within a company entity. Creating these entities is done through different mutations: customerRegister for customers and contactRegister for contacts. The parentId is the identifier of the container where the customer or company will be created. This ID can be found in the Propeller back office. The parentId for creating the contact is the companyId.

The customerRegister, companyCreate, and contactRegister mutations can be executed using the apiKey header using the limited api key.

curl https://api.propeller.com/graphql
-X POST
-H "Accept: application/json"
-H "apiKey: {LIMITED_API_KEY}"
-d "{{graphql_query_or_mutation}}"

Mutation: customerRegister

This mutation takes customer details such as firstName, lastName, email, and password and returns a new user session with access and refresh tokens.

Example GraphQL Query to create a customer:

mutation CustomerRegister {
  customerRegister(
    input: {
      firstName: "John"
      lastName: "Doe"
      email: "johndoe@example.com"
      phone: "123-456-7890"
      password: "your_password"
      parentId: 106
    }
  ) {
    session {
      accessToken
      refreshToken
      expirationTime
    }
    customer {
      __typename
      firstName
      middleName
      lastName
      email
      gender
      phone
      mobile
      primaryLanguage
      dateOfBirth
      isLoggedIn
      mailingList
      userId: customerId
      addresses {
        id
        code
        firstName
        middleName
        lastName
        gender
        email
        country
        city
        street
        number
        numberExtension
        postalCode
        company
        phone
        notes
        icp
        type
        isDefault
      }
    }
  }
}

Mutation: contactRegister

Before registering a contact, a company needs to be created using the companyCreate mutation. The companyId returned from this mutation should be used as the parentId in the contactRegister mutation.

Example GraphQL mutation to create a company:

mutation createCompany {
  companyCreate(
    input: { name: "ExampleCompany", taxNumber: "123456789", parentId: 107 }
  ) {
    companyId
    name
  }
}

Example GraphQL mutation to create a contact within a company:

mutation ContactRegister {
  contactRegister(
    input: {
      firstName: "Jane",
      lastName: "Smith",
      email: "janesmith@example.com",
      phone: "987-654-3210",
      password: "your_password",
      parentId: {companyId}  // Use the companyId returned from the createCompany mutation
    }
  ) {
    user {
      id
      userId
    }
    session {
      accessToken
      refreshToken
      expirationTime
    }
  }
}

3. Access and Refresh tokens

Once a customer or contact has been created, a login mutation needs to be executed to obtain the necessary tokens for authenticated requests:

mutation login {
  login(input: { email: "johndoe@example.com", password: "your_password" }) {
    session {
      accessToken
      refreshToken
      expirationTime
    }
  }
}

After a user successfully logs in, the login mutation returns an accessToken and a refreshToken. These tokens are essential for accessing Propeller's API securely.

• accessToken: Used to authenticate API requests.
• refreshToken: Used to generate new access tokens when the old one expires.
• expirationTime: The time at which the accessToken will expire. After this time, the access token will no longer be valid for authenticated requests.

Using the accessToken, you can now execute authenticated requests to the Propeller GraphQL API. This allows the user to access custom pricing, view order history, and manage favorite lists. Authenticated requests always need the combination of the apiKey and Authorization header

curl https://api.propeller.com/graphql
-X POST
-H "Accept: application/json"
-H "apiKey: {LIMITED_API_KEY}"
-H "Authorization: Bearer {accessToken}"
-d "{{graphql_query_or_mutation}}"

Viewer query

After logging in and obtaining the access token, you can use the viewer query to retrieve details about the logged-in user. This query provides comprehensive information about the user, including personal details and associated addresses.

Here is an example of the viewer query:

query {
  viewer {
    __typename
    firstName
    middleName
    lastName
    email
    gender
    phone
    mobile
    primaryLanguage
    dateOfBirth
    isLoggedIn
    mailingList
    ... on Contact {
      userId: contactId
      debtorId
      company {
        companyId
        name
        addresses {
          id
          code
          firstName
          middleName
          lastName
          gender
          email
          country
          city
          street
          number
          numberExtension
          postalCode
          company
          phone
          notes
          icp
          type
          isDefault
        }
      }
    }
    ... on Customer {
      userId: customerId
      debtorId
      addresses {
        id
        code
        firstName
        middleName
        lastName
        gender
        email
        country
        city
        street
        number
        numberExtension
        postalCode
        company
        phone
        notes
        icp
        type
        isDefault
      }
    }
  }
}

This query will return the user's personal information, such as their name, email, and contact details, as well as any associated addresses. The response will vary depending on whether the user is a Contact or a Customer.

Token Expiration

The expirationTime field in the login mutation response indicates the time at which the accessToken will expire. After this time, the access token will no longer be valid for authenticated requests. To continue making authenticated requests, you will need to use the refreshToken to obtain a new accessToken. It is important to handle token expiration in your application to ensure a seamless user experience.

Refresh Token Functionality

When the accessToken expires, you can use the refreshToken mutation to obtain a new accessToken and refreshToken by executing the following mutation:

mutation refreshToken {
  exchangeRefreshToken(
    input: {
      refreshToken: {refresh_token}
    }
  ) {
    access_token
    refresh_token
    expires_in
    token_type
    user_id
  }
}

This mutation will return a new access_token, refresh_token, and the expires_in field, which indicates the lifespan of the new access token. The token_type and user_id fields provide additional context about the token and the user.

By using the refresh token, you can maintain the user's authenticated session without requiring them to log in again, thus providing a smoother user experience.

Token Expiry Details

• accessToken expiry time: 3600 seconds / 1 hour
• refreshToken expiry time: does not expire

Refresh tokens expire only when one of the following occurs:

• The user is deleted
• The user is disabled
• A major account change is detected for the user. This includes events like password or email address updates.

Conclusion

By following this guide, you can securely register users, authenticate sessions and manage API access using Propeller Commerce’s GraphQL API. Implementing robust security practices such as token management and HTTPS will ensure that your system remains secure while providing access to Propeller’s comprehensive commerce functionalities.

For more details on the API calls and additional queries or mutations, refer to the Propeller API documentation.