diff --git a/docs/docs/30-administration/11-forges/50-bitbucket.md b/docs/docs/30-administration/11-forges/50-bitbucket.md
index 909da4d69..e611c552e 100644
--- a/docs/docs/30-administration/11-forges/50-bitbucket.md
+++ b/docs/docs/30-administration/11-forges/50-bitbucket.md
@@ -12,8 +12,8 @@ services:
     environment:
       - [...]
 +     - WOODPECKER_BITBUCKET=true
-+     - WOODPECKER_BITBUCKET_CLIENT=95c0282573633eb25e82
-+     - WOODPECKER_BITBUCKET_SECRET=30f5064039e6b359e075
++     - WOODPECKER_BITBUCKET_CLIENT=... # called "Key" in Bitbucket
++     - WOODPECKER_BITBUCKET_SECRET=...
 
   woodpecker-agent:
     [...]
@@ -21,24 +21,29 @@ services:
 
 ## Registration
 
-You must register your application with Bitbucket in order to generate a client and secret. Navigate to your account settings and choose OAuth from the menu, and click Add Consumer.
+You must register an OAuth application at Bitbucket in order to get a key and secret combination for woodpecker. Navigate to your workspace settings and choose `OAuth consumers` from the menu, and finally click `Add Consumer` (the url should be like: `https://bitbucket.org/[your-project-name]/workspace/settings/api`).
 
-Please use the Authorization callback URL:
+Please set a name and set the `Callback URL` like this:
 
 ```nohighlight
-http://woodpecker.mycompany.com/authorize
+https://<your-woodpecker-address>/authorize
 ```
 
+![bitbucket oauth setup](bitbucket_oauth.png)
+
 Please also be sure to check the following permissions:
 
 ```nohighlight
-Account:Email
-Account:Read
-Team Membership:Read
-Repositories:Read
-Webhooks:Read and Write
+Account: Email, Read
+Workspace membership: Read
+Projects: Read
+Repositories: Read
+Pull requests: Read
+Webhooks: Read and Write
 ```
 
+![bitbucket permissions](bitbucket_permissions.png)
+
 ## Configuration
 
 This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
@@ -51,7 +56,7 @@ Enables the Bitbucket driver.
 ### `WOODPECKER_BITBUCKET_CLIENT`
 > Default: empty
 
-Configures the Bitbucket OAuth client id. This is used to authorize access.
+Configures the Bitbucket OAuth client key. This is used to authorize access.
 
 ### `WOODPECKER_BITBUCKET_CLIENT_FILE`
 > Default: empty
diff --git a/docs/docs/30-administration/11-forges/bitbucket_oauth.png b/docs/docs/30-administration/11-forges/bitbucket_oauth.png
new file mode 100644
index 000000000..17ecf38ab
Binary files /dev/null and b/docs/docs/30-administration/11-forges/bitbucket_oauth.png differ
diff --git a/docs/docs/30-administration/11-forges/bitbucket_permissions.png b/docs/docs/30-administration/11-forges/bitbucket_permissions.png
new file mode 100644
index 000000000..0269f98b0
Binary files /dev/null and b/docs/docs/30-administration/11-forges/bitbucket_permissions.png differ