User-related API environment

Production user-related API docs

These pages describe the Production user-related API stack.

Use production OAuth credentials, production API base URLs, and production app URLs when following this documentation.

Need to test before going live? Switch to the Pre-live docs using the environment switcher above.

OAuth2 Scopes

Quran Foundation's OAuth 2.0 scopes limit the access granted to an access token. When requesting an access token, clients should request only the scopes they need. For User APIs, the user must consent to grant access to the scopes your app is requesting.

Parent and Child Scopes

Some API areas have a parent scope and more specific child scopes. For example, note is the parent scope for note.read, note.create, note.update, note.delete, and note.publish. A parent scope authorizes the matching child actions when calling Quran Foundation APIs.

When building an OAuth authorization URL, request the exact scopes approved for your client. If your client is approved for a parent scope such as note or post, request that parent scope directly. Do not also request child scopes unless those child scopes were separately approved for the client.

If your client is approved for	Request in the OAuth URL	Do not request unless separately approved
note	note	note.read note.create note.update note.delete note.publish
post	post	post.read post.create post.update post.delete post.save post.like post.report post.log post.export
collection	collection	collection.read collection.create collection.update collection.delete

Requesting a scope that is not approved for your client can cause the authorization server to return invalid_scope, even when a parent scope would be enough for the API call.

Standard OAuth2

Scope	Description
openid	OpenID Connect authentication
offline_access	Allows obtaining refresh tokens

Content

Scope	Description
content	Read Quran Foundation's non user-related content e.g. Tafsirs, Translations, etc

Search

Scope	Description
search	Search Quran Foundation's indexed content

Bookmarks

Scope	Description
bookmark	Manage your bookmarks
bookmark.read	Read your existing bookmarks
bookmark.create	Create a new bookmark
bookmark.delete	Delete your existing bookmarks

Collections

Scope	Description
collection	Manage your collections list
collection.read	Read your existing collections list
collection.create	Create a new collection
collection.update	Update your existing collections list
collection.delete	Delete your existing collections list

Reading Sessions

Scope	Description
reading_session	Manage your reading sessions
reading_session.read	See your latest reading sessions
reading_session.create	Create a new reading session
reading_session.update	Update your existing reading sessions

Preferences

Scope	Description
preference	Manage your reading and audio preferences
preference.read	See your current reading and audio preferences
preference.update	Update your current reading and audio preferences

Activity Days

Scope	Description
activity_day	Manage your activity days
activity_day.read	See your latest activity days
activity_day.create	Create a new activity day
activity_day.estimate	Estimate your reading speed of Ayahs
activity_day.update	Update your existing activity days
activity_day.delete	Delete your existing activity days

Goals

Scope	Description
goal	Manage your goal
goal.read	See your goal
goal.estimate	Estimate your goal's week plan
goal.create	Create a new goal
goal.update	Update your existing goal
goal.delete	Delete your existing goal

Streaks

Scope	Description
streak	Manage your streak
streak.read	See your streak
streak.update	Update your streak

Users

Scope	Description
user	Manage your user profile data
user.profile.read	Read your user profile data
user.profile.update	Update your user profile data
user.rooms.read	Read your rooms list
user.search	Search for users
user.follow	Follow/unfollow users
user.followers.read	Read user's followers list
user.following.read	Read user's following list

Posts

Scope	Description
post	Manage your QuranReflect posts
post.read	Read your QuranReflect timeline posts
post.create	Create a new QuranReflect post
post.update	Update your QuranReflect posts
post.delete	Delete your QuranReflect posts
post.save	Save QuranReflect posts to your profile
post.like	Like QuranReflect posts
post.report	Report QuranReflect posts
post.log	Track post views
post.export	Export posts (e.g., PDF)

Comments

Scope	Description
comment	Manage your QuranReflect post comments
comment.read	Read QuranReflect posts' comments
comment.create	Create a new QuranReflect post comment
comment.delete	Delete your QuranReflect post comments
comment.like	Like/unlike comments

Rooms

Scope	Description
room	Manage your QuranReflect rooms
room.read	Read room profiles and lists
room.create	Create new groups/pages
room.update	Update groups/pages
room.admin	Manage room admin access
room.search	Search for rooms
room.invite	Invite users, accept/reject invites
room.join	Join a group
room.leave	Leave a group
room.follow	Follow a page
room.unfollow	Unfollow a page
room.members.read	Read room members list
room.members.remove	Remove members from room
room.posts.read	Read posts in a room
room.posts.update	Update post privacy in room

Tags

Scope	Description
tag	Access tags
tag.read	Read/search tags

Notes

Scope	Description
note	Manage your notes
note.read	Read your notes
note.create	Create a new note
note.update	Update your notes
note.delete	Delete your notes
note.publish	Publish your notes