diff --git a/docs/uplinks.md b/docs/uplinks.md
index 9e70d291c..b606c9605 100644
--- a/docs/uplinks.md
+++ b/docs/uplinks.md
@@ -34,11 +34,46 @@ maxage | string | No |10m | all | limit maximun failure request | 2m
 fail_timeout | string | No |10m | all | defines max time when a request becomes a failure | 5m
 max_fails | number | No |2 | all | limit maximun failure request | 2
 cache | boolean | No |[true,false] | >= 2.1 | avoid cache tarballs | true
-auth | list | No | type: [bearer], [token: "token",token_env: [true,\<get name process.env\>]]  | >= 2.5 | assigns the header 'Authorization' see: http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules | disabled
+auth | list | No | see below  | >= 2.5 | assigns the header 'Authorization' see: http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules | disabled
 headers | list | No | authorization: "Bearer SecretJWToken==" | all | list of custom headers for the uplink | disabled
 strict_ssl |boolean | No | [true,false] | >= 3.0 | If true, requires SSL certificates be valid. | true
 
-> The `auth` property allows you to use a auth token via an environment variable, [clik here for an example](https://github.com/verdaccio/verdaccio/releases/tag/v2.5.0). 
+The `auth` property allows you to use an auth token with an uplink. Using the default environment variable:
+
+```yaml
+uplinks:
+  private:
+    url: https://private-registry.domain.com/registry
+    auth:
+      type: bearer
+      token_env: true # defaults to `process.env['NPM_TOKEN']`   
+```
+
+or via a specified environment variable: 
+
+```yaml
+uplinks:
+  private:
+    url: https://private-registry.domain.com/registry
+    auth:
+      type: bearer
+      token_env: FOO_TOKEN
+```
+
+`token_env: FOO_TOKEN `internally will use `process.env['FOO_TOKEN']`
+
+or by directly specifying a token:
+
+```yaml
+uplinks:
+  private:
+    url: https://private-registry.domain.com/registry
+    auth:
+      type: bearer
+      token: "token"
+```
+
+> Note: `token` has priority over `token_env`
 
 ### You Must know